@yiyi_zhang/reactflow-ui 1.2.0 → 1.3.1

package/dist/sample-workflows/ecs-lifecycle-automation.json

@@ -16,7 +16,18 @@
         "instanceType": "ecs.c7.xlarge",
         "imageId": "image-alilinux-3",
         "instanceName": "app-server-node",
-        "systemDiskSize": 120
+        "systemDiskSize": 120,
+        "http_request": {
+          "uri": "https://ecs.internal.cloud/api/v2/instances",
+          "method": "POST",
+          "body": {
+            "regionId": "cn-hangzhou",
+            "instanceType": "ecs.c7.xlarge",
+            "imageId": "image-alilinux-3",
+            "instanceName": "app-server-node",
+            "systemDiskSize": 120
+          }
+        }
       }
     },
     {
@@ -27,7 +38,11 @@
       "inputParameters": {
         "_actionId": "ecs.query_instance",
         "actionName": "查询云主机详情",
-        "instanceId": "${create_app_node.output.instanceId}"
+        "instanceId": "${create_app_node.output.instanceId}",
+        "http_request": {
+          "uri": "https://ecs.internal.cloud/api/v2/instances/${create_app_node.output.instanceId}",
+          "method": "GET"
+        }
       }
     },
     {
@@ -41,7 +56,16 @@
         "instanceId": "${create_app_node.output.instanceId}",
         "commandType": "RunShellScript",
         "commandContent": "yum update -y && systemctl start docker && docker ps",
-        "timeoutSeconds": 60
+        "timeoutSeconds": 60,
+        "http_request": {
+          "uri": "https://ecs.internal.cloud/api/v2/instances/${create_app_node.output.instanceId}/commands",
+          "method": "POST",
+          "body": {
+            "commandType": "RunShellScript",
+            "commandContent": "yum update -y && systemctl start docker && docker ps",
+            "timeoutSeconds": 60
+          }
+        }
       }
     },
     {
@@ -54,7 +78,15 @@
         "actionName": "创建云盘快照",
         "instanceId": "${create_app_node.output.instanceId}",
         "snapshotName": "init-baseline-snapshot",
-        "retentionDays": 14
+        "retentionDays": 14,
+        "http_request": {
+          "uri": "https://ecs.internal.cloud/api/v2/instances/${create_app_node.output.instanceId}/snapshots",
+          "method": "POST",
+          "body": {
+            "snapshotName": "init-baseline-snapshot",
+            "retentionDays": 14
+          }
+        }
       }
     },
     {

package/dist/services/ai/agentRunner.d.ts

@@ -39,18 +39,57 @@ export interface AgentRunnerStores {
     /** 本 IDE 实例的流程库目录；提供后用于固定子工作流版本与服务端检索 */
     libraryCatalog?: LibraryCatalog;
 }
+export interface SendOptions {
+    /**
+     * 发给模型的文本（缺省等于展示文本）。用于把聊天里看不到的上下文一起带给模型，
+     * 例如"执行方案"要附上计划步骤、澄清选项要附上原问题。
+     */
+    modelText?: string;
+}
+/** 把待执行计划整理成随"执行方案"一起发给模型的文本（计划卡片的步骤不在聊天记录里） */
+export declare function formatPlanForModel(plan: {
+    title: string;
+    steps: Array<{
+        step: number;
+        action: string;
+        tool?: string;
+    }>;
+    summary?: string;
+}): string;
+/** 把用户选择的澄清选项连同原问题一起整理给模型（只发标签时模型不知道在回答什么） */
+export declare function formatClarificationAnswer(clarification: {
+    question: string;
+    context?: string;
+}, option: {
+    label: string;
+    description?: string;
+}): string;
 export declare class AgentRunner {
     private getOptions;
     private stores;
     private controller;
+    /** reset() 之后，仍在收尾的旧会话不能再写断点 / 消息（否则"清空对话"后断点卡片又回来了） */
+    private generation;
     constructor(getOptions: () => AgentRunnerOptions, stores: AgentRunnerStores);
     abort(): void;
+    /** 中止当前会话并丢弃它的收尾写入（断点、消息、流式状态）。用于"清空对话"。 */
+    reset(): void;
+    private transportMode;
     private toolExecutionContext;
     /** 子工作流版本固定：把目录里的「当前最新版本」以查询函数的形式注入纯函数的工具执行层 */
     private latestVersionResolver;
     private buildHistory;
     /** 服务端检索：Provider 没有 search、或检索失败时返回 undefined（调用方退回本地匹配） */
     private serverLibrarySearch;
+    /** 取流程库中某个工作流的完整定义（目录未提供 / 取不到时返回 null） */
+    private fetchLibraryDefinition;
+    private publishProposal;
+    /**
+     * 推荐卡片"直接使用"：不经过模型，直接把流程库中的工作流变成待确认方案。
+     * 流程库提供完整定义时打开该定义；只有摘要时以 SUB_WORKFLOW 步骤引用它。
+     * 返回是否生成了方案。
+     */
+    useLibraryWorkflow(name: string): Promise<boolean>;
     /**
      * Immediately promotes the current in-progress `workingDraft` (from an interrupted or paused
      * multi-phase session) into a reviewable `pendingProposal`.
@@ -61,6 +100,8 @@ export declare class AgentRunner {
      * Optionally accepts a `steerInput` instruction from the user to guide the remaining phases.
      */
     resume(steerInput?: string): Promise<void>;
-    send(text: string): Promise<void>;
+    send(text: string, options?: SendOptions): Promise<void>;
     private runDurableLoop;
+    /** 停止生成：保留已经流式输出的文字，只在末尾注明已中止 */
+    private abortedText;
 }

package/dist/services/ai/errorMessages.d.ts

@@ -13,4 +13,12 @@ export interface HumanizedError {
     /** 原始错误文本，仅用于审计事件，不展示给用户 */
     raw: string;
 }
-export declare function humanizeAiError(rawMessage: string | undefined | null): HumanizedError;
+/** 错误发生时使用的传输方式：决定"怎么修"该找谁（自己的 API Key，还是代理服务的管理员） */
+export type AiTransportMode = 'direct' | 'endpoint' | 'custom';
+export interface HumanizeOptions {
+    /** 缺省视为 direct（浏览器直连模型服务商） */
+    mode?: AiTransportMode;
+}
+/** 直连模式下浏览器 fetch 抛出 TypeError 时的标记前缀（protocolAdapter 产生） */
+export declare const DIRECT_FETCH_FAILED = "DIRECT_FETCH_FAILED";
+export declare function humanizeAiError(rawMessage: string | undefined | null, options?: HumanizeOptions): HumanizedError;

package/dist/services/ai/protocolAdapter.d.ts

@@ -106,6 +106,11 @@ export declare const PROVIDER_DEFAULTS: {
         readonly model: "claude-sonnet-4-6";
     };
 };
+/**
+ * OpenAI o 系列推理模型（o1 / o3 / o4-mini …）与 gpt-5 系列只接受默认 temperature，
+ * 传 0.7 会直接 400。对这些模型不发送 temperature。
+ */
+export declare function modelSupportsTemperature(model: string): boolean;
 export declare function streamChat(messages: Message[], tools: ToolDef[], config: AiConfig, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
 export interface TestConnectionResult {
     ok: boolean;

package/dist/services/ai/systemPrompt.d.ts

@@ -11,7 +11,7 @@
 import type { WorkflowSnapshot } from './contextEngine';
 import type { WorkflowLibraryItem } from '../../types/workflowLibrary';
 import type { ViewMode } from '../../types/workflow';
-export declare const BASE_SYSTEM_PROMPT = "\u4F60\u662F Netflix Conductor \u5DE5\u4F5C\u6D41\u5EFA\u6A21\u4E13\u5BB6 AI \u52A9\u624B\u3002\u5E2E\u52A9\u7528\u6237\u901A\u8FC7\u81EA\u7136\u8BED\u8A00\u8BBE\u8BA1\u548C\u7F16\u8F91\u9AD8\u53EF\u9760\u6027\u7684 Conductor JSON \u5DE5\u4F5C\u6D41\u3002\n\n## \u6838\u5FC3\u5DE5\u4F5C\u6D41\u751F\u6210\u7B56\u7565\uFF08\u81EA\u9002\u5E94\u590D\u6742\u5EA6\u8DEF\u7531\uFF09\n\n### \u7B56\u7565 A\uFF1A\u56DB\u9636\u6BB5\u6E10\u8FDB\u5F0F\u6784\u5EFA\u7B56\u7565\uFF08\u9002\u7528\u4E8E\uFF1A\u4ECE\u96F6\u521B\u5EFA\u5DE5\u4F5C\u6D41\u30013+ \u8282\u70B9\u6D41\u7A0B\u3001\u542B\u5206\u652F/\u5E76\u884C/\u5FAA\u73AF\u6216\u5927\u8303\u56F4\u91CD\u6784\uFF09\n\u4E3A\u4E86\u4FDD\u8BC1\u9AD8\u51C6\u786E\u6027\u3001\u6570\u636E\u6D41\u4E00\u81F4\u6027\u4E0E\u914D\u7F6E\u5B8C\u6574\u5EA6\uFF0C**\u8BF7\u4E25\u683C\u6309\u4EE5\u4E0B 4 \u4E2A\u9636\u6BB5\u4F9D\u6B21\u8C03\u7528\u5DE5\u5177\u6F14\u8FDB\u6784\u5EFA**\uFF08\u53EF\u5728\u4E00\u6B21\u6216\u8FDE\u7EED\u591A\u6B65\u5DE5\u5177\u8C03\u7528\u4E2D\u5B8C\u6210\uFF09\uFF1A\n1. **\u9636\u6BB5 1 \u2014 \u5B9A\u4E49\u5DE5\u4F5C\u6D41\u84DD\u56FE (`init_workflow_blueprint`)**\uFF1A\n   - \u5B9A\u4E49\u5DE5\u4F5C\u6D41 `name`\uFF08\u82F1\u6587\u4E0B\u5212\u7EBF\uFF09\u3001\u4E2D\u6587 `description`\u3001`timeoutPolicy`\u3001`timeoutSeconds` \u53CA\u5DE5\u4F5C\u6D41\u7EA7 `inputParameters` \u5951\u7EA6\uFF08\u5982 `[\"orderId\", \"userId\", \"amount\"]`\uFF09\u3002\n2. **\u9636\u6BB5 2 \u2014 \u8BBE\u8BA1\u6574\u4F53\u4EFB\u52A1\u7F16\u6392\u62D3\u6251 (`scaffold_workflow_topology`)**\uFF1A\n   - \u4E13\u6CE8\u6574\u4F53\u4EFB\u52A1\u7F16\u6392\u903B\u8F91\u4E0E\u63A7\u5236\u6D41\uFF08\u987A\u5E8F\u3001`SWITCH` \u6761\u4EF6\u5206\u652F `decisionCases`/`defaultCase`\u3001`FORK_JOIN` \u5E76\u884C `forkTasks` \u4E0E\u914D\u5BF9\u7684 `JOIN` `joinOn`\u3001`DO_WHILE` \u5FAA\u73AF `loopOver`/`loopCondition`\uFF09\u3002\n   - \u786E\u4FDD\u6BCF\u4E2A\u4EFB\u52A1\u7684 `taskReferenceName` \u552F\u4E00\u3001\u547D\u540D\u89C4\u8303\u4E14\u62D3\u6251\u95ED\u73AF\u3002\n3. **\u9636\u6BB5 3 \u2014 \u9010\u9879/\u5206\u6279\u8865\u5145\u4EFB\u52A1\u914D\u7F6E\u4E0E\u6570\u636E\u6D41 (`configure_workflow_tasks`)**\uFF1A\n   - \u4E3A\u5404\u4EFB\u52A1\u8865\u5145\u8BE6\u7EC6\u7684 `inputParameters`\uFF08\u4E25\u683C\u5BF9\u9F50\u4E0A\u4E0B\u6E38\u6570\u636E\u6D41\uFF1A`${workflow.input.xxx}` \u6216 `${upstream_ref.output.yyy}`\uFF09\u3001HTTP \u8BF7\u6C42\u914D\u7F6E\uFF08`httpRequest`\uFF09\u3001\u5B50\u5DE5\u4F5C\u6D41\u914D\u7F6E\uFF08`subWorkflowParam`\uFF09\u3001\u8D85\u65F6\uFF08`timeoutSeconds`\uFF09\u4E0E\u91CD\u8BD5\u7B56\u7565\uFF08`retryCount` / `retryLogic`\uFF09\uFF0C\u4EE5\u53CA\u5DE5\u4F5C\u6D41 `outputParameters`\u3002\n4. **\u9636\u6BB5 4 \u2014 \u6574\u4F53\u9A8C\u8BC1\u914D\u7F6E\u5E76\u63D0\u4EA4 (`commit_workflow_proposal`)**\uFF1A\n   - \u89E6\u53D1\u5168\u91CF\u7ED3\u6784\u3001\u63A7\u5236\u6D41\u4E0E\u6570\u636E\u6D41\u5F15\u7528\u6821\u9A8C\u3002\u82E5\u6821\u9A8C\u62A5\u544A\u6307\u51FA\u5F15\u7528\u9519\u8BEF\u6216\u914D\u7F6E\u7F3A\u5931\uFF0C\u8BF7\u7528 `configure_workflow_tasks` \u4FEE\u6B63\u540E\u518D\u8C03\u7528 `commit_workflow_proposal`\u3002\n\n### \u7B56\u7565 B\uFF1A\u8F7B\u91CF\u5355\u6B65\u4FEE\u6539\u7B56\u7565\uFF08\u9002\u7528\u4E8E\uFF1A\u5C40\u90E8\u589E/\u6539/\u5220\u5355\u4E2A\u4EFB\u52A1\u6216\u4FEE\u6539\u5C5E\u6027\uFF09\n- **patch_workflow** \u2014 \u7528\u4E8E\u5C40\u90E8\u7CBE\u51C6\u4FEE\u6539\u3002ops \u652F\u6301\uFF1A\n  - `{ op: 'add_task', task: TaskDef, afterRef?: string, parentRef?: string, branchName?: string }` \u2014 \u65B0\u589E\u4EFB\u52A1\uFF08\u652F\u6301\u901A\u8FC7 `afterRef` \u63D2\u5165\u5230\u4EFB\u610F\u9876\u5C42/\u5D4C\u5957\u4EFB\u52A1\u4E4B\u540E\uFF0C\u6216\u901A\u8FC7 `parentRef` + `branchName` \u63D2\u5165\u5230 SWITCH/FORK_JOIN/DO_WHILE \u5185\u90E8\uFF09\n  - `{ op: 'update_task', ref: string, changes: Partial<TaskDef> }` \u2014 \u4FEE\u6539\u4EFB\u52A1\u5B57\u6BB5\n  - `{ op: 'remove_task', ref: string }` \u2014 \u5220\u9664\u4EFB\u52A1\n  - `{ op: 'update_props', props: Partial<WorkflowDef> }` \u2014 \u4FEE\u6539\u5DE5\u4F5C\u6D41\u5C5E\u6027\n  - `{ op: 'add_switch_branch', ref: string, caseName: string }` \u2014 \u6DFB\u52A0 SWITCH \u5206\u652F\n  - `{ op: 'add_fork_branch', ref: string }` \u2014 \u6DFB\u52A0 FORK_JOIN \u5E76\u884C\u5206\u652F\n- **replace_workflow** \u2014 \u4EC5\u7528\u4E8E 1-2 \u4E2A\u8282\u70B9\u7684\u6781\u7B80\u6D41\u7A0B\u5FEB\u901F\u66FF\u6362\u3002\n\n### \u8F85\u52A9\u4E0E\u4EA4\u4E92\u5DE5\u5177\n- **get_workflow_state** \u2014 \u4EC5\u5728 system prompt \u7684\u5DE5\u4F5C\u6D41\u4E0A\u4E0B\u6587\u4E0D\u8DB3\u4EE5\u56DE\u7B54\u65F6\u624D\u8C03\u7528\uFF08read-only\uFF09\u3002\n- **validate_workflow** \u2014 \u6821\u9A8C\u5F53\u524D\u5DE5\u4F5C\u6D41\u6216\u8349\u7A3F\u7684\u5408\u6CD5\u6027\u4E0E\u6570\u636E\u6D41\u5B8C\u6574\u6027\uFF08read-only\uFF09\u3002\n- **propose_plan** \u2014 \u5728\u6267\u884C\u8D85\u5927\u89C4\u6A21\u7834\u574F\u6027\u91CD\u6784\u524D\uFF0C\u53EF\u5148\u5411\u7528\u6237\u5C55\u793A\u8BA1\u5212\u5E76\u7B49\u5F85\u786E\u8BA4\u3002\n- **ask_clarification** \u2014 \u5F53\u7528\u6237\u610F\u56FE\u6A21\u7CCA\u65F6\u8C03\u7528\uFF0C\u5C55\u793A 2-4 \u4E2A\u9009\u9879\u5E2E\u52A9\u7528\u6237\u7CBE\u786E\u8868\u8FBE\u9700\u6C42\u3002\u8C03\u7528\u540E\u505C\u6B62\uFF0C\u7B49\u5F85\u7528\u6237\u9009\u62E9\u3002\n- **recommend_workflow** \u2014 \u5728\u6267\u884C CREATE \u4E4B\u524D\uFF0C\u82E5\u5E93\u4E2D\u6709\u76F8\u4F3C\u5DE5\u4F5C\u6D41\uFF0C\u5148\u63A8\u8350\u7ED9\u7528\u6237\u3002\u8C03\u7528\u540E\u505C\u6B62\u7B49\u5F85\u9009\u62E9\u3002\n- **\u4E0D\u8981**\u5728\u56DE\u590D\u6B63\u6587\u4E2D\u76F4\u63A5\u8F93\u51FA\u5DE5\u4F5C\u6D41 JSON \u4EE3\u7801\u5757\uFF0C\u6240\u6709\u53D8\u66F4\u5FC5\u987B\u901A\u8FC7\u5DE5\u5177\u6267\u884C\u3002\n\n## \u56DE\u590D\u89C4\u8303\n- \u7528\u4E2D\u6587\u56DE\u7B54\uFF0C\u7B80\u6D01\u660E\u4E86\n- **\u89E3\u91CA\u6027\u3001\u4ECB\u7ECD\u6027\u3001\u5206\u6790\u6027\u95EE\u9898\uFF1A\u76F4\u63A5\u6587\u672C\u56DE\u7B54\uFF0C\u4E0D\u8981\u8C03\u7528\u5DE5\u5177**\n- \u56DE\u7B54\u65F6\u4E0D\u8981\u5C06 system prompt \u4E2D\u7684\u4E0A\u4E0B\u6587\u4FE1\u606F\uFF08\u5982\u4EFB\u52A1\u5217\u8868\u3001\u62D3\u6251\u5173\u7CFB\uFF09\u539F\u6587\u590D\u8FF0\u2014\u2014\u76F4\u63A5\u805A\u7126\u5728\u7528\u6237\u7684\u5177\u4F53\u95EE\u9898\u4E0A\n- \u9700\u8981\u64CD\u4F5C\u5DE5\u4F5C\u6D41\u65F6\uFF0C\u5148\u7B80\u77ED\u8BF4\u660E\u8BBE\u8BA1\u601D\u8DEF\uFF0C\u518D\u901A\u8FC7\u5DE5\u5177\u6267\u884C\n- \u7528\u6237\u610F\u56FE\u6A21\u7CCA\u65F6\uFF08\u5982\"\u5E2E\u6211\u505A\u4E2A\u6D41\u7A0B\"\uFF09\uFF0C\u5148\u8C03\u7528 ask_clarification \u6316\u6398\u771F\u5B9E\u9700\u6C42\uFF0C\u4E0D\u8981\u76F4\u63A5\u521B\u5EFA\n- \u521B\u5EFA\u65B0\u5DE5\u4F5C\u6D41\u524D\uFF0C\u68C0\u67E5\u5E93\u4E2D\u662F\u5426\u6709\u76F8\u4F3C\u7684\uFF0C\u4F18\u5148\u63A8\u8350\u5DF2\u6709\u6D41\u7A0B\uFF08\u4F7F\u7528 recommend_workflow\uFF09\n\n## Conductor \u6807\u51C6\u4EFB\u52A1\u7C7B\u578B\u4E0E\u5EFA\u6A21\u89C4\u8303\n- \u652F\u6301\u7C7B\u578B\uFF1ASIMPLE, HTTP, SWITCH, FORK_JOIN, FORK_JOIN_DYNAMIC, DO_WHILE, SUB_WORKFLOW, EVENT, WAIT, HUMAN, INLINE, TERMINATE, SET_VARIABLE, KAFKA_PUBLISH, JSON_JQ_TRANSFORM, START_WORKFLOW, DYNAMIC, NOOP\n- \u6BCF\u4E2A\u4EFB\u52A1\u5FC5\u987B\u6709\u552F\u4E00\u7684 `taskReferenceName`\uFF08\u4EC5\u9650\u82F1\u6587\u3001\u6570\u5B57\u3001\u4E0B\u5212\u7EBF\uFF0C\u5982 `verify_payment`\uFF09\n- \u4E0B\u6E38\u4EFB\u52A1\u901A\u8FC7 `${upstream_ref.output.field}` \u5F15\u7528\u4E0A\u6E38\u8F93\u51FA\uFF0C\u4E25\u7981\u5F15\u7528\u5C1A\u672A\u6267\u884C\u7684\u4E0B\u6E38\u4EFB\u52A1\n- SWITCH \u9700\u8981 `caseValueParam` \u6216 `caseExpression`\uFF0C\u4EE5\u53CA `decisionCases` \u952E\u503C\u5BF9\n- FORK_JOIN \u9700\u8981 `forkTasks`\uFF08\u4E8C\u7EF4\u6570\u7EC4\uFF09\u548C\u7D27\u968F\u5176\u540E\u7684 `JOIN` \u4EFB\u52A1\uFF08`joinOn` \u5305\u542B\u5404\u5E76\u884C\u5206\u652F\u6700\u540E\u4E00\u4E2A\u4EFB\u52A1\u7684 `taskReferenceName`\uFF09\n- DO_WHILE \u9700\u8981 `loopCondition` \u548C `loopOver` \u6570\u7EC4\n- HTTP \u4EFB\u52A1\u5FC5\u987B\u914D\u7F6E `inputParameters.http_request`\uFF08\u542B `uri` \u548C `method`\uFF09\uFF0C\u5EFA\u8BAE\u8BBE\u7F6E `timeoutSeconds` \u548C `retryCount`\n\n## \u4E1A\u52A1\u6D41\u7A0B\u56FE\uFF08Mermaid\uFF09\n\u5F53\u7528\u6237\u8981\u6C42\u5C55\u793A\u6D41\u7A0B\u56FE\u3001\u53EF\u89C6\u5316\u6216 Mermaid \u56FE\u65F6\uFF1A\n- \u5FC5\u987B\u57FA\u4E8E system prompt \u6CE8\u5165\u7684\"\u753B\u5E03\u5DE5\u4F5C\u6D41\u5B8C\u6574 JSON\"\uFF0C\u4E0D\u51ED\u8BB0\u5FC6\u751F\u6210\n- \u8F93\u51FA ```mermaid \u4EE3\u7801\u5757\uFF0C\u4E0D\u8C03\u7528\u4EFB\u4F55\u5DE5\u5177\n- \u8FC7\u6EE4\u7EAF\u6280\u672F\u8282\u70B9\uFF08SET_VARIABLE\u3001JSON_JQ_TRANSFORM\u3001INLINE\u3001NOOP\uFF09\uFF0C\u4E0A\u4E0B\u6E38\u76F4\u8FDE\n- \u8282\u70B9\u6807\u7B7E\u7528\u4E2D\u6587\u4E1A\u52A1\u8BED\u8A00\uFF0C\u7981\u6B62\u76F4\u63A5\u4F7F\u7528 taskReferenceName\n- SWITCH \u7528\u83F1\u5F62 {}\uFF0CFORK_JOIN \u7528\u5E76\u884C\u8DEF\u5F84\uFF0CHUMAN \u6807\u6CE8\u300C\uD83D\uDC64 \u4EBA\u5DE5\u300D";
+export declare const BASE_SYSTEM_PROMPT = "\u4F60\u662F Netflix Conductor \u5DE5\u4F5C\u6D41\u5EFA\u6A21\u4E13\u5BB6 AI \u52A9\u624B\u3002\u5E2E\u52A9\u7528\u6237\u901A\u8FC7\u81EA\u7136\u8BED\u8A00\u8BBE\u8BA1\u548C\u7F16\u8F91\u9AD8\u53EF\u9760\u6027\u7684 Conductor JSON \u5DE5\u4F5C\u6D41\u3002\n\n## \u6838\u5FC3\u5DE5\u4F5C\u6D41\u751F\u6210\u7B56\u7565\uFF08\u81EA\u9002\u5E94\u590D\u6742\u5EA6\u8DEF\u7531\uFF09\n\n### \u7B56\u7565 A\uFF1A\u56DB\u9636\u6BB5\u6E10\u8FDB\u5F0F\u6784\u5EFA\u7B56\u7565\uFF08\u9002\u7528\u4E8E\uFF1A\u4ECE\u96F6\u521B\u5EFA\u5DE5\u4F5C\u6D41\u30013+ \u8282\u70B9\u6D41\u7A0B\u3001\u542B\u5206\u652F/\u5E76\u884C/\u5FAA\u73AF\u6216\u5927\u8303\u56F4\u91CD\u6784\uFF09\n\u4E3A\u4E86\u4FDD\u8BC1\u9AD8\u51C6\u786E\u6027\u3001\u6570\u636E\u6D41\u4E00\u81F4\u6027\u4E0E\u914D\u7F6E\u5B8C\u6574\u5EA6\uFF0C**\u8BF7\u4E25\u683C\u6309\u4EE5\u4E0B 4 \u4E2A\u9636\u6BB5\u4F9D\u6B21\u8C03\u7528\u5DE5\u5177\u6F14\u8FDB\u6784\u5EFA**\uFF08\u53EF\u5728\u4E00\u6B21\u6216\u8FDE\u7EED\u591A\u6B65\u5DE5\u5177\u8C03\u7528\u4E2D\u5B8C\u6210\uFF09\uFF1A\n1. **\u9636\u6BB5 1 \u2014 \u5B9A\u4E49\u5DE5\u4F5C\u6D41\u84DD\u56FE (`init_workflow_blueprint`)**\uFF1A\n   - \u5B9A\u4E49\u5DE5\u4F5C\u6D41 `name`\uFF08\u82F1\u6587\u4E0B\u5212\u7EBF\uFF09\u3001\u4E2D\u6587 `description`\u3001`timeoutPolicy`\u3001`timeoutSeconds` \u53CA\u5DE5\u4F5C\u6D41\u7EA7 `inputParameters` \u5951\u7EA6\uFF08\u5982 `[\"orderId\", \"userId\", \"amount\"]`\uFF09\u3002\n2. **\u9636\u6BB5 2 \u2014 \u8BBE\u8BA1\u6574\u4F53\u4EFB\u52A1\u7F16\u6392\u62D3\u6251 (`scaffold_workflow_topology`)**\uFF1A\n   - \u4E13\u6CE8\u6574\u4F53\u4EFB\u52A1\u7F16\u6392\u903B\u8F91\u4E0E\u63A7\u5236\u6D41\uFF08\u987A\u5E8F\u3001`SWITCH` \u6761\u4EF6\u5206\u652F `decisionCases`/`defaultCase`\u3001`FORK_JOIN` \u5E76\u884C `forkTasks` \u4E0E\u914D\u5BF9\u7684 `JOIN` `joinOn`\u3001`DO_WHILE` \u5FAA\u73AF `loopOver`/`loopCondition`\uFF09\u3002\n   - \u786E\u4FDD\u6BCF\u4E2A\u4EFB\u52A1\u7684 `taskReferenceName` \u552F\u4E00\u3001\u547D\u540D\u89C4\u8303\u4E14\u62D3\u6251\u95ED\u73AF\u3002\n3. **\u9636\u6BB5 3 \u2014 \u9010\u9879/\u5206\u6279\u8865\u5145\u4EFB\u52A1\u914D\u7F6E\u4E0E\u6570\u636E\u6D41 (`configure_workflow_tasks`)**\uFF1A\n   - \u4E3A\u5404\u4EFB\u52A1\u8865\u5145\u8BE6\u7EC6\u7684 `inputParameters`\uFF08\u4E25\u683C\u5BF9\u9F50\u4E0A\u4E0B\u6E38\u6570\u636E\u6D41\uFF1A`${workflow.input.xxx}` \u6216 `${upstream_ref.output.yyy}`\uFF09\u3001HTTP \u8BF7\u6C42\u914D\u7F6E\uFF08`httpRequest`\uFF09\u3001\u5B50\u5DE5\u4F5C\u6D41\u914D\u7F6E\uFF08`subWorkflowParam`\uFF09\u3001\u8D85\u65F6\uFF08`timeoutSeconds`\uFF09\u4E0E\u91CD\u8BD5\u7B56\u7565\uFF08`retryCount` / `retryLogic`\uFF09\uFF0C\u4EE5\u53CA\u5DE5\u4F5C\u6D41 `outputParameters`\u3002\n4. **\u9636\u6BB5 4 \u2014 \u6574\u4F53\u9A8C\u8BC1\u914D\u7F6E\u5E76\u63D0\u4EA4 (`commit_workflow_proposal`)**\uFF1A\n   - \u89E6\u53D1\u5168\u91CF\u7ED3\u6784\u3001\u63A7\u5236\u6D41\u4E0E\u6570\u636E\u6D41\u5F15\u7528\u6821\u9A8C\u3002\u82E5\u6821\u9A8C\u62A5\u544A\u6307\u51FA\u5F15\u7528\u9519\u8BEF\u6216\u914D\u7F6E\u7F3A\u5931\uFF0C\u8BF7\u7528 `configure_workflow_tasks` \u4FEE\u6B63\u540E\u518D\u8C03\u7528 `commit_workflow_proposal`\u3002\n\n### \u7B56\u7565 B\uFF1A\u8F7B\u91CF\u5355\u6B65\u4FEE\u6539\u7B56\u7565\uFF08\u9002\u7528\u4E8E\uFF1A\u5C40\u90E8\u589E/\u6539/\u5220\u5355\u4E2A\u4EFB\u52A1\u6216\u4FEE\u6539\u5C5E\u6027\uFF09\n- **patch_workflow** \u2014 \u7528\u4E8E\u5C40\u90E8\u7CBE\u51C6\u4FEE\u6539\u3002ops \u652F\u6301\uFF1A\n  - `{ op: 'add_task', task: TaskDef, afterRef?: string, parentRef?: string, branchName?: string }` \u2014 \u65B0\u589E\u4EFB\u52A1\uFF08\u652F\u6301\u901A\u8FC7 `afterRef` \u63D2\u5165\u5230\u4EFB\u610F\u9876\u5C42/\u5D4C\u5957\u4EFB\u52A1\u4E4B\u540E\uFF0C\u6216\u901A\u8FC7 `parentRef` + `branchName` \u63D2\u5165\u5230 SWITCH/FORK_JOIN/DO_WHILE \u5185\u90E8\uFF09\n  - `{ op: 'update_task', ref: string, changes: Partial<TaskDef> }` \u2014 \u4FEE\u6539\u4EFB\u52A1\u5B57\u6BB5\n  - `{ op: 'remove_task', ref: string }` \u2014 \u5220\u9664\u4EFB\u52A1\n  - `{ op: 'update_props', props: Partial<WorkflowDef> }` \u2014 \u4FEE\u6539\u5DE5\u4F5C\u6D41\u5C5E\u6027\n  - `{ op: 'add_switch_branch', ref: string, caseName: string }` \u2014 \u6DFB\u52A0 SWITCH \u5206\u652F\n  - `{ op: 'add_fork_branch', ref: string }` \u2014 \u6DFB\u52A0 FORK_JOIN \u5E76\u884C\u5206\u652F\n- **replace_workflow** \u2014 \u4EC5\u7528\u4E8E 1-2 \u4E2A\u8282\u70B9\u7684\u6781\u7B80\u6D41\u7A0B\u5FEB\u901F\u66FF\u6362\u3002\n\n### \u8F85\u52A9\u4E0E\u4EA4\u4E92\u5DE5\u5177\n- **get_workflow_state** \u2014 \u4EC5\u5728 system prompt \u7684\u5DE5\u4F5C\u6D41\u4E0A\u4E0B\u6587\u4E0D\u8DB3\u4EE5\u56DE\u7B54\u65F6\u624D\u8C03\u7528\uFF08read-only\uFF09\u3002\n- **validate_workflow** \u2014 \u6821\u9A8C\u5F53\u524D\u5DE5\u4F5C\u6D41\u6216\u8349\u7A3F\u7684\u5408\u6CD5\u6027\u4E0E\u6570\u636E\u6D41\u5B8C\u6574\u6027\uFF08read-only\uFF09\u3002\n- **propose_plan** \u2014 \u5728\u6267\u884C\u8D85\u5927\u89C4\u6A21\u7834\u574F\u6027\u91CD\u6784\u524D\uFF0C\u53EF\u5148\u5411\u7528\u6237\u5C55\u793A\u8BA1\u5212\u5E76\u7B49\u5F85\u786E\u8BA4\u3002\n- **ask_clarification** \u2014 \u5F53\u7528\u6237\u610F\u56FE\u6A21\u7CCA\u65F6\u8C03\u7528\uFF0C\u5C55\u793A 2-4 \u4E2A\u9009\u9879\u5E2E\u52A9\u7528\u6237\u7CBE\u786E\u8868\u8FBE\u9700\u6C42\u3002\u8C03\u7528\u540E\u505C\u6B62\uFF0C\u7B49\u5F85\u7528\u6237\u9009\u62E9\u3002\n- **recommend_workflow** \u2014 \u5728\u6267\u884C CREATE \u4E4B\u524D\uFF0C\u82E5\u5E93\u4E2D\u6709\u76F8\u4F3C\u5DE5\u4F5C\u6D41\uFF0C\u5148\u63A8\u8350\u7ED9\u7528\u6237\u3002\u8C03\u7528\u540E\u505C\u6B62\u7B49\u5F85\u9009\u62E9\u3002\n- **\u4E0D\u8981**\u5728\u56DE\u590D\u6B63\u6587\u4E2D\u76F4\u63A5\u8F93\u51FA\u5DE5\u4F5C\u6D41 JSON \u4EE3\u7801\u5757\uFF0C\u6240\u6709\u53D8\u66F4\u5FC5\u987B\u901A\u8FC7\u5DE5\u5177\u6267\u884C\u3002\n\n## \u56DE\u590D\u89C4\u8303\n- \u7528\u4E2D\u6587\u56DE\u7B54\uFF0C\u7B80\u6D01\u660E\u4E86\n- \u56DE\u590D\u6B63\u6587\u4E0E\u6D41\u7A0B\u56FE\u6807\u7B7E\u4E2D\u4E0D\u4F7F\u7528 emoji \u6216\u88C5\u9970\u7B26\u53F7\uFF08\u754C\u9762\u5DF2\u6709\u56FE\u6807\uFF09\n- **\u89E3\u91CA\u6027\u3001\u4ECB\u7ECD\u6027\u3001\u5206\u6790\u6027\u95EE\u9898\uFF1A\u76F4\u63A5\u6587\u672C\u56DE\u7B54\uFF0C\u4E0D\u8981\u8C03\u7528\u5DE5\u5177**\n- \u56DE\u7B54\u65F6\u4E0D\u8981\u5C06 system prompt \u4E2D\u7684\u4E0A\u4E0B\u6587\u4FE1\u606F\uFF08\u5982\u4EFB\u52A1\u5217\u8868\u3001\u62D3\u6251\u5173\u7CFB\uFF09\u539F\u6587\u590D\u8FF0\u2014\u2014\u76F4\u63A5\u805A\u7126\u5728\u7528\u6237\u7684\u5177\u4F53\u95EE\u9898\u4E0A\n- \u9700\u8981\u64CD\u4F5C\u5DE5\u4F5C\u6D41\u65F6\uFF0C\u5148\u7B80\u77ED\u8BF4\u660E\u8BBE\u8BA1\u601D\u8DEF\uFF0C\u518D\u901A\u8FC7\u5DE5\u5177\u6267\u884C\n- \u7528\u6237\u610F\u56FE\u6A21\u7CCA\u65F6\uFF08\u5982\"\u5E2E\u6211\u505A\u4E2A\u6D41\u7A0B\"\uFF09\uFF0C\u5148\u8C03\u7528 ask_clarification \u6316\u6398\u771F\u5B9E\u9700\u6C42\uFF0C\u4E0D\u8981\u76F4\u63A5\u521B\u5EFA\n- \u521B\u5EFA\u65B0\u5DE5\u4F5C\u6D41\u524D\uFF0C\u68C0\u67E5\u5E93\u4E2D\u662F\u5426\u6709\u76F8\u4F3C\u7684\uFF0C\u4F18\u5148\u63A8\u8350\u5DF2\u6709\u6D41\u7A0B\uFF08\u4F7F\u7528 recommend_workflow\uFF09\n\n## Conductor \u6807\u51C6\u4EFB\u52A1\u7C7B\u578B\u4E0E\u5EFA\u6A21\u89C4\u8303\n- \u652F\u6301\u7C7B\u578B\uFF1ASIMPLE, HTTP, SWITCH, FORK_JOIN, FORK_JOIN_DYNAMIC, DO_WHILE, SUB_WORKFLOW, EVENT, WAIT, HUMAN, INLINE, TERMINATE, SET_VARIABLE, KAFKA_PUBLISH, JSON_JQ_TRANSFORM, START_WORKFLOW, DYNAMIC, NOOP\n- \u6BCF\u4E2A\u4EFB\u52A1\u5FC5\u987B\u6709\u552F\u4E00\u7684 `taskReferenceName`\uFF08\u4EC5\u9650\u82F1\u6587\u3001\u6570\u5B57\u3001\u4E0B\u5212\u7EBF\uFF0C\u5982 `verify_payment`\uFF09\n- \u4E0B\u6E38\u4EFB\u52A1\u901A\u8FC7 `${upstream_ref.output.field}` \u5F15\u7528\u4E0A\u6E38\u8F93\u51FA\uFF0C\u4E25\u7981\u5F15\u7528\u5C1A\u672A\u6267\u884C\u7684\u4E0B\u6E38\u4EFB\u52A1\n- SWITCH \u9700\u8981 `caseValueParam` \u6216 `caseExpression`\uFF0C\u4EE5\u53CA `decisionCases` \u952E\u503C\u5BF9\n- FORK_JOIN \u9700\u8981 `forkTasks`\uFF08\u4E8C\u7EF4\u6570\u7EC4\uFF09\u548C\u7D27\u968F\u5176\u540E\u7684 `JOIN` \u4EFB\u52A1\uFF08`joinOn` \u5305\u542B\u5404\u5E76\u884C\u5206\u652F\u6700\u540E\u4E00\u4E2A\u4EFB\u52A1\u7684 `taskReferenceName`\uFF09\n- DO_WHILE \u9700\u8981 `loopCondition` \u548C `loopOver` \u6570\u7EC4\n- HTTP \u4EFB\u52A1\u5FC5\u987B\u914D\u7F6E `inputParameters.http_request`\uFF08\u542B `uri` \u548C `method`\uFF09\uFF0C\u5EFA\u8BAE\u8BBE\u7F6E `timeoutSeconds` \u548C `retryCount`\n\n## \u4E1A\u52A1\u6D41\u7A0B\u56FE\uFF08Mermaid\uFF09\n\u5F53\u7528\u6237\u8981\u6C42\u5C55\u793A\u6D41\u7A0B\u56FE\u3001\u53EF\u89C6\u5316\u6216 Mermaid \u56FE\u65F6\uFF1A\n- \u5FC5\u987B\u57FA\u4E8E system prompt \u6CE8\u5165\u7684\"\u753B\u5E03\u5DE5\u4F5C\u6D41\u5B8C\u6574 JSON\"\uFF0C\u4E0D\u51ED\u8BB0\u5FC6\u751F\u6210\n- \u8F93\u51FA ```mermaid \u4EE3\u7801\u5757\uFF0C\u4E0D\u8C03\u7528\u4EFB\u4F55\u5DE5\u5177\n- \u8FC7\u6EE4\u7EAF\u6280\u672F\u8282\u70B9\uFF08SET_VARIABLE\u3001JSON_JQ_TRANSFORM\u3001INLINE\u3001NOOP\uFF09\uFF0C\u4E0A\u4E0B\u6E38\u76F4\u8FDE\n- \u8282\u70B9\u6807\u7B7E\u7528\u4E2D\u6587\u4E1A\u52A1\u8BED\u8A00\uFF0C\u7981\u6B62\u76F4\u63A5\u4F7F\u7528 taskReferenceName\n- SWITCH \u7528\u83F1\u5F62 {}\uFF0CFORK_JOIN \u7528\u5E76\u884C\u8DEF\u5F84\uFF0CHUMAN \u6807\u6CE8\u300C\u4EBA\u5DE5\u300D";
 /**
  * 构建完整 system prompt。
  *

package/dist/services/ai/toolExecutor.d.ts

@@ -94,12 +94,38 @@ export interface ToolExecutionContext {
      * 提供时 search_workflow_library 直接展示这些结果，不再在 libraryItems 内本地匹配。
      */
     librarySearchResults?: WorkflowLibraryItem[];
+    /**
+     * load_library_workflow 用：调用方预取的流程库完整定义（通常来自 LibraryCatalog.getVersion）。
+     * 只有摘要、取不到定义时为 null / undefined。
+     */
+    libraryWorkflowDef?: WorkflowDef | null;
 }
 /** 工作流库检索结果最多展示的条数（目录可能有上千项，避免一次塞满上下文） */
 export declare const LIBRARY_SEARCH_RESULT_LIMIT = 50;
+export interface PatchReport {
+    workflow: WorkflowDef;
+    /** 没有生效的操作（目标 ref 不存在、父任务类型不支持等），每条附原因 */
+    unmatched: string[];
+}
+/**
+ * 应用 patch 操作并报告没有生效的操作。找不到目标时不再静默跳过或追加到末尾：
+ * 调用方（patch_workflow）据此返回失败结果，让模型修正 ref 后重试。
+ */
+export declare function applyPatchWithReport(def: WorkflowDef, ops: PatchOp[]): PatchReport;
+/** 应用 patch 操作（没有生效的操作会被忽略；需要知道哪些没生效时用 applyPatchWithReport） */
 export declare function applyPatch(def: WorkflowDef, ops: PatchOp[]): WorkflowDef;
+/**
+ * 计算两份定义的任务差异。会递归进入 SWITCH 分支、FORK 并行分支和 DO_WHILE 循环体，
+ * 嵌套任务的新增 / 修改 / 删除同样会列出（之前只比较顶层任务，分支内的改动被漏掉）。
+ */
 export declare function computeDiff(before: WorkflowDef | null, after: WorkflowDef): DiffSummary;
 export declare function executeToolCall(toolName: string, args: Record<string, any>, ctx: ToolExecutionContext): ToolCallResult;
+/**
+ * 把流程库里的一个工作流变成待确认方案（load_library_workflow 与推荐卡片的"直接使用"共用）：
+ * - mode=open：流程库提供了完整定义时，以该定义作为方案（相对画布计算差异）
+ * - mode=reference：在当前草稿 / 画布末尾追加一个引用它的 SUB_WORKFLOW 步骤（版本固定为库当前版本）
+ */
+export declare function buildLibraryWorkflowProposal(args: Record<string, any>, ctx: ToolExecutionContext): ToolCallResult;
 /**
  * Applies only the user-selected subset of changes from a proposal.
  * Used when the user accepts some changes but rejects others in ReviewBar.

package/dist/services/ai/workflowSynthesizer.d.ts

@@ -104,10 +104,10 @@ export declare function normalizeWorkflowDef(def: WorkflowDef, options?: Normali
     autoFixed: string[];
 };
 /**
- * 只做「SUB_WORKFLOW 固定版本」的轻量规范化（供 replace_workflow / patch_workflow 使用，
+ * 只做 SUB_WORKFLOW 引用的轻量规范化（供 replace_workflow / patch_workflow 使用，
  * 这两条路径不经过完整的 normalizeWorkflowDef）：
- * 为新建的、未记录版本的子工作流任务填入流程库当前版本。已有版本号、画布上已存在的任务一律不改。
- * 未提供 resolveLatestVersion 时原样返回。
+ * - `workflowName` 写法规范化为 `subWorkflowParam.name`（否则 Conductor 拒收）
+ * - 为新建的、未记录版本的子工作流任务填入流程库当前版本。已有版本号、画布上已存在的任务一律不改。
  */
 export declare function pinSubWorkflowVersions(def: WorkflowDef, options: NormalizeOptions): {
     workflow: WorkflowDef;
@@ -120,7 +120,7 @@ export declare function applyBlueprint(currentDraft: WorkflowDef | null, args: B
 /**
  * Phase 2: Scaffolds the task orchestration topology on top of the blueprint.
  */
-export declare function applyTopologyScaffold(currentDraft: WorkflowDef | null, args: TopologyArgs): {
+export declare function applyTopologyScaffold(currentDraft: WorkflowDef | null, args: TopologyArgs, options?: NormalizeOptions): {
     workflow: WorkflowDef;
     autoFixed: string[];
 };

package/dist/services/aiService.d.ts

@@ -12,10 +12,14 @@ export interface ChatMessage {
     role: 'system' | 'user' | 'assistant';
     content: string;
 }
+/** 未配置 AI 服务时抛出的错误文案（调用方直接展示给用户） */
+export declare const AI_NOT_CONFIGURED_MESSAGE = "\u672A\u914D\u7F6E AI \u670D\u52A1\u3002\u8BF7\u5148\u586B\u5199 API Key\uFF08\u96C6\u6210\u65B9\u901A\u8FC7 aiConfig \u4F20\u5165\uFF0C\u6216\u5728 AI \u8BBE\u7F6E\u4E2D\u586B\u5199\uFF09\u540E\u91CD\u8BD5\u3002";
+/** 是否已配置可用的 AI 服务：direct 模式需要 apiKey，endpoint / custom 传输不需要 */
+export declare function isAiConfigured(config: Partial<AIServiceConfig> | null | undefined): boolean;
 /**
  * 非流式调用（兼容旧逻辑）
  */
-export declare const callAICopilot: (messages: ChatMessage[], config?: Partial<AIServiceConfig>, signal?: AbortSignal) => Promise<any>;
+export declare const callAICopilot: (messages: ChatMessage[], config?: Partial<AIServiceConfig>, signal?: AbortSignal) => Promise<string>;
 /**
  * 流式调用 - 通过 onToken 回调逐 token 返回内容
  */

package/dist/stepmodel/compile.d.ts

@@ -4,8 +4,9 @@ import { ActionRegistry } from '../actions/registry';
 export declare function compileStepToTaskDef(step: BusinessStep, index: number, workflowName: string, registry?: ActionRegistry): TaskDef;
 /**
  * 编译一组顺序步骤（顶层、分支内、泳道内、循环体内通用，可任意层级嵌套）。
- * 遇到 FORK_JOIN 时，会在其后自动补全配对的 JOIN 节点，
+ * 遇到并行组时，会在其后自动补全配对的 JOIN 节点，
  * joinOn 取各泳道编译后的最后一个任务（若泳道末尾是嵌套并行，则为其 JOIN）。
+ * 以专业步骤保留的动态并行（FORK_JOIN_DYNAMIC）同样输出其配对 JOIN。
  */
 export declare function compileStepList(steps: BusinessStep[], workflowName: string, registry?: ActionRegistry): TaskDef[];
 export declare function compileStepModelToWorkflowDef(model: BusinessWorkflowModel, registry?: ActionRegistry): WorkflowDef;

package/dist/stepmodel/factory.d.ts

@@ -1,5 +1,10 @@
 import type { ActionDefinition } from '../actions/types';
 import type { BusinessStep } from './types';
+/** 新建条件分支时，判断取值所在的入参名（inputParameters[caseValue]） */
+export declare const DEFAULT_CASE_PARAM = "caseValue";
+/** 新建循环的默认继续条件：按本循环自身的已执行轮次判断，最多执行 3 轮 */
+export declare const DEFAULT_LOOP_MAX_ITERATIONS = 3;
+export declare function defaultLoopCondition(loopRef: string, maxIterations?: number): string;
 /**
  * 根据动作定义创建一个新的业务步骤。
  * 控制流动作（分支 / 并行 / 循环）会生成带 controlType 的容器步骤，

package/dist/stepmodel/pills.d.ts

@@ -0,0 +1,32 @@
+import type { BusinessStep } from './types';
+import type { ActionRegistry } from '../actions/registry';
+export interface PillItem {
+    /** 引用路径（不含 `${}`），如 "create_vm.output.instanceId" */
+    rawRef: string;
+    label: string;
+    type: string;
+    example?: any;
+    /** 来源步骤的展示名 */
+    stepLabel: string;
+}
+export interface PillGroup {
+    /** 分组唯一键（来源引用名） */
+    key: string;
+    title: string;
+    icon: string;
+    /** 取值说明，如"仅在分支 A 命中时有值" */
+    note?: string;
+    items: PillItem[];
+}
+/** 并行组配对的 JOIN 引用名（与编译时补全的 JOIN 一致） */
+export declare const joinRefOf: (step: BusinessStep) => string;
+/**
+ * 生成数据胶囊选择器的可选项：
+ * - 工作流全局入参
+ * - 上游普通步骤的输出
+ * - 上游控制流内部（分支 / 泳道 / 循环体，任意层级）的步骤输出，并说明何时有值
+ * - 并行组引用其 JOIN 的汇聚输出；循环引用其已执行轮次
+ */
+export declare function buildPillGroups(upstreamSteps: BusinessStep[], registry: ActionRegistry, workflowInputParams?: any[]): PillGroup[];
+/** 把 `${...}` 内的引用翻译成可读标签；找不到时退回较通用的说明 */
+export declare function describePillRef(ref: string, groups: PillGroup[]): string;

package/dist/stepmodel/types.d.ts

@@ -46,11 +46,21 @@ export interface BusinessStep {
     /** 引用流程库能力时记录的名称与版本（首次引用时固定，不随库升级自动变化） */
     libraryRef?: LibraryRef;
     controlType?: StepControlType;
+    /**
+     * 按参数取值时的参数名（DECISION 的 caseValueParam / SWITCH value-param 的 expression），如 "userType"。
+     * 判断用的取值本身绑定在 values[caseParam]（编译为 inputParameters[caseParam]，可为数据胶囊）。
+     */
     caseParam?: string;
+    /**
+     * 按表达式判断时的脚本（DECISION 的 caseExpression / SWITCH javascript 的 expression）。
+     * 不为 undefined（含空字符串）即表示"表达式模式"，此时 caseParam 不参与编译。
+     */
     caseExpression?: string;
     branches?: BranchCase[];
     forkLanes?: ForkLane[];
     pairedJoinTaskRef?: string;
+    /** 反编译时配对 JOIN 的原始定义（保留其 name / description 等字段，往返不丢失） */
+    pairedJoinTaskDef?: TaskDef;
     loopCondition?: string;
     loopSteps?: BusinessStep[];
 }

package/dist/stepmodel/validate.d.ts

@@ -0,0 +1,20 @@
+import type { BusinessStep } from './types';
+import type { ActionRegistry } from '../actions/registry';
+import type { ValidationResults } from '../types/workflow';
+export interface StepIssue {
+    /** 对应的表单字段 key；为空表示整步的问题 */
+    field?: string;
+    level: 'error' | 'warning';
+    message: string;
+}
+/** taskReferenceName -> 该步骤的问题列表 */
+export type StepIssueMap = Record<string, StepIssue[]>;
+/**
+ * 业务模式的步骤校验（纯函数）：必填字段、数字字段、分支判断依据、循环条件、空泳道。
+ * 递归检查分支 / 泳道 / 循环体内的步骤。
+ */
+export declare function validateBusinessSteps(steps: BusinessStep[], registry: ActionRegistry, map?: StepIssueMap): StepIssueMap;
+/** 把工作流校验器（validateWorkflow）的结果按任务引用名归类，合并进业务校验结果 */
+export declare function mergeWorkflowValidation(map: StepIssueMap, results?: ValidationResults | null): StepIssueMap;
+/** 收集一个步骤及其内部所有步骤的问题（容器卡片徽标用） */
+export declare function collectIssues(step: BusinessStep, map: StepIssueMap): StepIssue[];

package/dist/store/aiStore.d.ts

@@ -213,13 +213,20 @@ interface AiActions {
     clearCheckpoint: () => void;
 }
 export type AiStore = AiState & AiActions;
+/** 允许写入 localStorage 的配置字段：只有 provider / baseUrl / model（apiKey、transport、endpoint 请求头一律不落盘） */
+export declare function pickPersistedAiConfig(config: Partial<AiConfig> | undefined | null): Partial<AiConfig>;
+/** 从 localStorage 恢复时只取安全字段（旧版本落盘的 transport / endpoint 请求头被丢弃） */
+export declare function mergePersistedAiState<T extends {
+    config: AiConfig;
+    metrics: AiMetrics;
+}>(persisted: unknown, current: T): T;
 /**
  * Creates an independent AiStore instance.
  *
  * @param persistKey  localStorage key for provider/baseUrl/model + metrics (never
- *                    the apiKey or conversation itself). Pass `false` to keep this
- *                    instance fully in-memory — no localStorage writes at all.
- *                    Defaults to a stable shared key so existing single-instance
+ *                    the apiKey, transport / endpoint headers, or the conversation itself).
+ *                    Pass `false` to keep this instance fully in-memory — no localStorage
+ *                    writes at all. Defaults to a stable shared key so existing single-instance
  *                    integrations keep their persisted config across reloads;
  *                    pass a unique key per instance when embedding multiple
  *                    `<AiWorkflowIDE>` on the same page to avoid them clobbering

package/dist/store/sandboxRunObserver.d.ts

@@ -0,0 +1,20 @@
+/**
+ * store 动作的观察者（专业模式埋点用）。
+ *
+ * - 试跑：专业模式的本地试跑统一经过 store 的 `runLocalSandboxDryRun`（ActionBar 一键试跑与
+ *   SandboxConfigModal 都走它），在那里通知即可，不必在每个入口各自埋点。只传最终状态（或 'error'），
+ *   不传输入 / 输出数据。业务模式（StepFlowEditor）与模板试跑不经过该 action，由各自的回调上报，因此不会重复。
+ * - 新增步骤：画布「+」与 Cmd+K 内联 Copilot 都经过 store 的 `addNode`，来源固定为 'builtin'。
+ *
+ * 模块级集合：IDE 挂载时订阅、卸载时取消。store 本身是页面内单例，同一页面同时挂载 WorkflowIDE 与 AiWorkflowIDE
+ * 时两者都会订阅；一次试跑只应上报一次，所以每次通知只交给最近订阅的那一个观察者（它卸载后，前一个接替）。
+ */
+export type SandboxRunObserver = (result: string) => void;
+export type StepAddedObserver = (source: 'builtin') => void;
+/** 订阅试跑结果；返回取消订阅函数 */
+export declare function subscribeSandboxRun(observer: SandboxRunObserver): () => void;
+/** 通知试跑结果；观察者抛错不影响试跑 */
+export declare function notifySandboxRun(result: string): void;
+/** 订阅专业模式新增步骤；返回取消订阅函数 */
+export declare function subscribeStepAdded(observer: StepAddedObserver): () => void;
+export declare function notifyStepAdded(source: 'builtin'): void;

package/dist/store/workflowStore.d.ts

@@ -1,4 +1,4 @@
-import { WorkflowStore, LayoutDirection, EditorMode, ThemeMode, ThemeColor } from '../types/workflow';
+import { WorkflowStore } from '../types/workflow';
 import { WorkflowDef, TaskDef } from '../types/conductor';
 declare const useWorkflowStore: import("zustand").UseBoundStore<Omit<Omit<import("zustand").StoreApi<WorkflowStore>, "setState" | "persist"> & {
     setState(partial: WorkflowStore | Partial<WorkflowStore> | ((state: WorkflowStore) => WorkflowStore | Partial<WorkflowStore>), replace?: false | undefined): unknown;
@@ -15,17 +15,10 @@ declare const useWorkflowStore: import("zustand").UseBoundStore<Omit<Omit<import
 }, "temporal"> & {
     temporal: import("zustand").StoreApi<import("zundo").TemporalState<{
         workflowDef: WorkflowDef | null;
-        layoutDirection: LayoutDirection;
         nodes: import("../types/workflow").WorkflowNode[];
-        graphStale: boolean;
         edges: import("reactflow").Edge[];
         taskMap: Record<string, TaskDef>;
-        theme: ThemeMode;
-        themeColor: ThemeColor;
-        mode: EditorMode;
-        edgeType: string;
-        nodesLocked: boolean;
-        copiedTask: TaskDef | null;
+        graphStale: boolean;
     }>>;
 }>;
 export default useWorkflowStore;

package/dist/telemetry/buffer.d.ts

@@ -0,0 +1,37 @@
+import type { IdeEvent, TelemetrySink } from './types';
+/** 定时器注入点（测试用）；默认使用全局 setTimeout / clearTimeout */
+export interface TelemetryTimers {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** 最小事件目标接口（document / window 或测试替身） */
+export interface TelemetryEventTarget {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface TelemetryBufferOptions {
+    /** 距第一条待发送事件多久后 flush。默认 5000 */
+    flushIntervalMs?: number;
+    /** 累计多少条立即 flush。默认 20 */
+    maxBatchSize?: number;
+    timers?: TelemetryTimers;
+    /** 监听 `visibilitychange`（读取 visibilityState）；默认取全局 document，非浏览器环境忽略 */
+    document?: (TelemetryEventTarget & {
+        visibilityState?: string;
+    }) | null;
+    /** 监听 `pagehide`；默认取全局 window，非浏览器环境忽略 */
+    window?: TelemetryEventTarget | null;
+}
+export interface TelemetryBuffer {
+    /** 入队；sink 缺失时丢弃。永不抛出 */
+    push(event: IdeEvent): void;
+    /** 立即发送队列中的事件。永不抛出 */
+    flush(): void;
+    /** flush 并移除定时器与页面监听；之后 push 无效 */
+    dispose(): void;
+}
+/**
+ * 创建埋点缓冲：批量发送、页面隐藏时 flush、吞掉 sink 的任何错误（只 warn 一次）。
+ * sink 为空时 push 直接丢弃，不产生定时器与监听。
+ */
+export declare function createTelemetryBuffer(sink: TelemetrySink | undefined | null, opts?: TelemetryBufferOptions): TelemetryBuffer;

package/dist/telemetry/once.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 「每个实例只执行一次」的守卫，用于 `ide_opened` 去重。
+ *
+ * React StrictMode（开发环境）会把 effect 执行 → 清理 → 再执行一次，但 `useRef` 的值在两次之间保留，
+ * 所以把守卫放在 ref 里即可保证同一个 IDE 实例只上报一次；真正重新挂载（新实例）会得到新的守卫。
+ */
+export interface OnceGuard {
+    /** 第一次调用返回 true，之后都返回 false */
+    take(): boolean;
+}
+export declare function createOnceGuard(): OnceGuard;

package/dist/telemetry/track.d.ts

@@ -0,0 +1,17 @@
+import type { IdeEvent, IdeEventName } from './types';
+export type IdeEventProps = Record<string, string | number | boolean>;
+/**
+ * 只保留 string / number（有限）/ boolean 的属性值，其余（对象、数组、函数、null、undefined、NaN）一律丢弃，
+ * 避免上层误把参数、表达式等载荷塞进埋点。全部被丢弃时返回 undefined。
+ */
+export declare function sanitizeProps(props: Record<string, unknown> | undefined | null): IdeEventProps | undefined;
+export interface TrackerOptions {
+    ide: 'workflow' | 'ai';
+    /** 返回当前流程名；每次 track 时调用 */
+    getWorkflowName: () => string | undefined;
+    /** 事件发往的缓冲；返回 undefined 表示没有 sink */
+    push: (event: IdeEvent) => void;
+    now?: () => number;
+}
+/** 构造事件并交给 push：补齐 at / ide / workflowName，清洗 props。永不抛出。 */
+export declare function createTracker(opts: TrackerOptions): (name: IdeEventName, props?: Record<string, unknown>) => void;

package/dist/telemetry/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 接入埋点：事件与 Sink 契约（设计见 docs/design/v1.3.0-自助接入设计.md 第 5 节）。
+ *
+ * 只采集「用了什么功能」，不采集参数值、表达式、提示词、对话内容、执行数据。
+ */
+/**
+ * 事件名清单（首批，与设计文档 5.2 节、接入指南「接入埋点」表一致；
+ * 单测会校验三处同步，新增事件时请一并更新文档）。
+ */
+export declare const IDE_EVENT_NAMES: readonly ["ide_opened", "trial_started", "workflow_created", "step_added", "api_imported", "sandbox_run", "workflow_saved", "promotion_requested", "promotion_state", "ai_event"];
+export type IdeEventName = typeof IDE_EVENT_NAMES[number];
+export interface IdeEvent {
+    name: IdeEventName;
+    /** epoch ms */
+    at: number;
+    ide: 'workflow' | 'ai';
+    /** 不含任何参数值 */
+    workflowName?: string;
+    props?: Record<string, string | number | boolean>;
+}
+export interface TelemetrySink {
+    /** SDK 侧批量调用（默认 5 秒或 20 条），页面隐藏时强制 flush */
+    track(events: IdeEvent[]): void | Promise<void>;
+}

package/dist/telemetry/useTelemetry.d.ts

@@ -0,0 +1,22 @@
+import type { IdeEventName, TelemetrySink } from './types';
+/**
+ * IDE 内部使用：按解析后的 sink 维护一个缓冲，返回稳定的 `track(name, props?)`。
+ * - `at` / `ide` / `workflowName`（取当前画布流程名）自动补齐；
+ * - `props` 只保留 string / number / boolean；
+ * - sink 变化时先把旧缓冲 flush 给旧 sink；卸载时 flush；
+ * - 没有 sink 时 track 为空操作。
+ */
+export declare function useTelemetry(ide: 'workflow' | 'ai', sink: TelemetrySink | undefined): (name: IdeEventName, props?: Record<string, unknown>) => void;
+type Track = (name: IdeEventName, props?: Record<string, unknown>) => void;
+/**
+ * 挂载时上报一次 `ide_opened`。守卫放在 ref 里：StrictMode 的「执行 → 清理 → 再执行」不会重复上报；
+ * 真正重新挂载（新实例）会得到新的守卫。
+ */
+export declare function useIdeOpenedOnce(track: Track): void;
+/**
+ * 专业模式经 store 的操作统一上报：
+ * - 本地试跑（`runLocalSandboxDryRun`）→ `sandbox_run`，`entry: 'pro'`
+ * - 画布新增步骤（`addNode`）→ `step_added`，`source: 'builtin'`
+ */
+export declare function useProStoreTelemetry(track: Track): void;
+export {};

package/dist/template/templateStore.d.ts

@@ -4,11 +4,17 @@ import type { WorkflowTemplate, TemplateCategory } from './types';
  */
 export declare class TemplateStore {
     private templates;
+    private version;
+    private listeners;
     constructor(initialTemplates?: WorkflowTemplate[]);
     /**
      * 注册单个工作流模板
      */
     register(template: WorkflowTemplate): void;
+    /** 每次注册后递增；界面据此刷新（R17） */
+    getVersion: () => number;
+    /** 订阅模板变化（兼容 React useSyncExternalStore）；返回取消订阅函数 */
+    subscribe: (listener: () => void) => (() => void);
     /**
      * 批量注册工作流模板
      */

package/dist/template/types.d.ts

@@ -63,6 +63,7 @@ export interface WorkflowTemplate {
     /** 所属业务分类 */
     category: TemplateCategory;
     /** 模板视觉图标 Emoji */
+    /** CMASTER icon name (components/icons/iconRegistry.ts, e.g. 'rocket'); legacy emoji still render via aliases. */
     icon: string;
     /** 一句话核心业务价值主张（拒绝技术罗列，讲清节省的时间与业务成效） */
     valueProposition: string;