@yiyi_zhang/reactflow-ui 0.3.0 → 0.5.0-beta.0

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

@@ -0,0 +1,51 @@
+/**
+ * AgentRunner — the AI agentic loop, extracted from AiCommandCenter (M2.1)
+ *
+ * Owns the entire multi-step tool-calling loop that used to live inline in a
+ * 300-line useCallback: streaming the model, dispatching tool calls, self-healing
+ * invalid proposals, and committing results (messages/proposal/plan/repair/
+ * clarification/recommendation) to aiStore. This makes the orchestration logic
+ * testable headlessly (see agentRunner.test.ts) and keeps AiCommandCenter as a
+ * thin renderer of store state.
+ *
+ * Store access: this is the ONE place in the AI stack allowed to read
+ * workflowStore/libraryStore/aiStore directly (via getState()) and call aiStore
+ * actions to commit results — everything it calls into (toolExecutor,
+ * systemPrompt, contextEngine) is a pure function that receives that state
+ * explicitly, so those modules stay unit-testable without a store.
+ *
+ * Instancing (M3.2): `aiStore`/`libraryStore`/`toolRegistry` are injected via the
+ * constructor rather than imported as module singletons, so each `<AiWorkflowIDE>`
+ * mount gets its own isolated runner talking to its own store/registry instances
+ * (see store/ideStoresContext.tsx). `workflowStore` remains a shared singleton for
+ * now — see the architecture review's M3.2 note on that being a larger follow-up.
+ */
+import type { AiStore } from '../../store/aiStore';
+import type { LibraryStore } from '../../store/libraryStore';
+import type { ToolRegistry } from './toolRegistry';
+import type { AiEvent } from '../../types/aiEvents';
+import type { UseBoundStore, StoreApi } from 'zustand';
+export interface AgentRunnerOptions {
+    systemPrompt?: string;
+    systemPromptExtra?: string;
+    aiPermissions?: {
+        canEdit?: boolean;
+        canRepair?: boolean;
+    };
+    onAiEvent?: (event: AiEvent) => void;
+}
+export interface AgentRunnerStores {
+    aiStore: UseBoundStore<StoreApi<AiStore>>;
+    libraryStore: UseBoundStore<StoreApi<LibraryStore>>;
+    toolRegistry: ToolRegistry;
+}
+export declare class AgentRunner {
+    private getOptions;
+    private stores;
+    private controller;
+    constructor(getOptions: () => AgentRunnerOptions, stores: AgentRunnerStores);
+    abort(): void;
+    private toolExecutionContext;
+    private buildHistory;
+    send(text: string): Promise<void>;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * AI Context Engine — 从工作流快照构建 AI 上下文
+ *
+ * 生成精简的结构化上下文，避免全量 JSON dump 消耗过多 token。
+ * 不直接依赖 workflowStore——调用方（AgentRunner）读取实时 store 状态后
+ * 以 WorkflowSnapshot 形式传入，使本模块保持纯函数、可脱离 store 单测。
+ */
+import type { Edge } from 'reactflow';
+import type { WorkflowDef, TaskDef, WorkflowInstance } from '../../types/conductor';
+import type { EditorMode, TaskExecutionData, ValidationResults } from '../../types/workflow';
+/** 调用方（AgentRunner）从 workflowStore 读取的实时状态快照 */
+export interface WorkflowSnapshot {
+    workflowDef: WorkflowDef | null;
+    edges: Edge[];
+    selectedTask: TaskDef | null;
+    executionData: Record<string, TaskExecutionData> | null;
+    mode: EditorMode;
+    workflowInstance: WorkflowInstance | null;
+    taskMap: Record<string, TaskDef>;
+    validationResults: ValidationResults;
+}
+export interface ExecutionContext {
+    /** 实例 ID（截短） */
+    instanceId?: string;
+    /** 工作流整体状态 */
+    workflowStatus?: string;
+    /** 失败任务 */
+    failedTasks: Array<{
+        ref: string;
+        type: string;
+        reason?: string;
+    }>;
+    /** 进行中的任务 */
+    inProgressTasks: string[];
+    /** 已完成任务数 */
+    completedCount: number;
+    /** 总任务数 */
+    totalCount: number;
+}
+export interface WorkflowContext {
+    /** 一句话摘要 */
+    summary: string;
+    /** 拓扑关系（文字表达） */
+    topology: string;
+    /** 任务列表摘要 */
+    tasks: Array<{
+        ref: string;
+        name: string;
+        type: string;
+    }>;
+    /** 当前选中任务的上下文 */
+    focusTask?: FocusTaskContext;
+    /** 校验问题 */
+    validationIssues: string[];
+    /** 运行态执行上下文（run 模式下注入） */
+    execution?: ExecutionContext;
+    /** 完整工作流 JSON (仅在需要全量信息时提供) */
+    fullDef?: any;
+}
+interface FocusTaskContext {
+    task: {
+        ref: string;
+        name: string;
+        type: string;
+        inputParameters?: any;
+    };
+    upstreamRefs: string[];
+    downstreamRefs: string[];
+    /** 运行态：该任务的执行状态和失败原因 */
+    executionStatus?: string;
+    executionFailureReason?: string;
+}
+/**
+ * 构建工作流上下文摘要
+ */
+export declare function buildContext(snapshot: WorkflowSnapshot, options?: {
+    includeFull?: boolean;
+}): WorkflowContext;
+/**
+ * 将 WorkflowContext 格式化为 system prompt 中的上下文段落
+ */
+export declare function formatContextForPrompt(ctx: WorkflowContext): string;
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * Draft Persistence — 刷新不丢工作（M1.4）
+ *
+ * AiWorkflowIDE 默认所有状态存于内存，刷新页面即丢失全部编辑。这里提供一个
+ * 可选的、集成方显式开启的 localStorage 草稿机制：workflowDef + 对话 + 待确认
+ * 提案定期写入本地存储，挂载时检测到草稿则恢复现场。
+ *
+ * 默认不开启（`draftPersist={false}`）——是否写宿主页面的 localStorage 由集成方决定。
+ */
+import type { WorkflowDef } from '../../types/conductor';
+import type { AiChatMessage, ProposedChange } from '../../store/aiStore';
+export interface IdeDraft {
+    workflowDef: WorkflowDef | null;
+    messages: AiChatMessage[];
+    pendingProposal: ProposedChange | null;
+    savedAt: number;
+}
+/** 判断草稿是否包含有意义的内容（避免刚挂载、仅有欢迎语时就落一份空草稿） */
+export declare function isMeaningfulDraft(workflowDef: WorkflowDef | null, messages: AiChatMessage[], pendingProposal: ProposedChange | null): boolean;
+export declare function loadDraft(key: string): IdeDraft | null;
+export declare function saveDraft(key: string, draft: IdeDraft): void;
+export declare function clearDraft(key: string): void;

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

@@ -0,0 +1,16 @@
+/**
+ * Error Messages — 面向业务用户的两段式错误文案（M1.5）
+ *
+ * 原始错误（HTTP 状态码、provider 报错原文、网络异常类名等）对不熟悉 Conductor/LLM
+ * 的业务用户没有意义，且直接把它们塞进聊天气泡会让人不知道发生了什么、更不知道怎么办。
+ *
+ * 这里把常见错误模式翻译成"发生了什么 + 你能做什么"的中文提示；原始文本只通过
+ * `onAiEvent({ type: 'ai:error', rawMessage })` 提供给审计/日志，绝不进入聊天 UI。
+ */
+export interface HumanizedError {
+    /** 展示给用户的两段式文案（发生了什么 + 能做什么） */
+    display: string;
+    /** 原始错误文本，仅用于审计事件，不展示给用户 */
+    raw: string;
+}
+export declare function humanizeAiError(rawMessage: string | undefined | null): HumanizedError;

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

@@ -0,0 +1,17 @@
+/**
+ * AI Intent Classifier — 本地规则快速分类用户意图
+ *
+ * 不消耗 AI token，通过关键词匹配快速判断用户输入的意图类型，
+ * 用于动态调整上下文注入粒度和 prompt 模板。
+ */
+export type Intent = 'CREATE' | 'ADD' | 'MODIFY' | 'DELETE' | 'REFACTOR' | 'EXPLAIN' | 'DEBUG' | 'OPTIMIZE' | 'VISUALIZE' | 'GENERAL' | 'VAGUE';
+/**
+ * 对用户输入进行意图分类
+ */
+export declare function classifyIntent(input: string): Intent;
+/**
+ * 根据意图决定上下文注入粒度
+ */
+export declare function getContextOptions(intent: Intent): {
+    includeFull: boolean;
+};

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

@@ -0,0 +1,114 @@
+/**
+ * AI Protocol Adapter — OpenAI / Anthropic 双协议统一适配
+ *
+ * 支持的协议：
+ * - OpenAI Chat Completions API（/chat/completions）
+ *   兼容提供商：OpenAI、Mistral、DeepSeek、Groq、Together.ai、Azure OpenAI、
+ *              Ollama、LM Studio、vLLM 等任意 OpenAI 兼容服务
+ * - Anthropic Messages API（/messages）
+ *
+ * baseUrl 和 model 均为可选，不填时自动使用各提供商默认值。
+ *
+ * 传输模式：`config.transport` 未设置时，以下 provider/apiKey/baseUrl/model 字段
+ * 生效为 **direct 模式**——浏览器直连模型服务商，API Key 留存于终端用户浏览器，
+ * 仅建议用于开发调试。生产环境请通过 `transport: { type: 'endpoint', url }` 配置
+ * 集成方自己的后端代理，详见 `./transport.ts`。
+ */
+import type { AiTransport } from './transport';
+export type { AiTransport, AgentRequest } from './transport';
+export interface AiConfig {
+    /**
+     * 协议类型：
+     * - 'openai'     — OpenAI Chat Completions 协议（Mistral/Groq/DeepSeek 等兼容服务也选此项）
+     * - 'anthropic'  — Anthropic Messages 协议
+     * - 'auto'       — 根据 baseUrl 自动判断（包含 anthropic.com → Anthropic，其余 → OpenAI）
+     * @default 'auto'
+     */
+    provider?: 'openai' | 'anthropic' | 'auto';
+    /** API Key（仅 direct 模式需要；使用 endpoint/custom 传输时可留空字符串） */
+    apiKey: string;
+    /**
+     * API 基础 URL（不含路径，仅 direct 模式生效）。
+     * 留空时使用各提供商标准地址：
+     * - OpenAI:    https://api.openai.com/v1
+     * - Anthropic: https://api.anthropic.com
+     *
+     * 常见第三方示例：
+     * - Mistral:   https://api.mistral.ai/v1
+     * - DeepSeek:  https://api.deepseek.com/v1
+     * - Groq:      https://api.groq.com/openai/v1
+     * - Ollama:    http://localhost:11434/v1
+     * - Azure:     https://{resource}.openai.azure.com/openai/deployments/{deploy}
+     */
+    baseUrl?: string;
+    /**
+     * 模型名称（仅 direct 模式生效）。留空时使用各提供商默认模型：
+     * - OpenAI:    gpt-4o
+     * - Anthropic: claude-sonnet-4-6
+     */
+    model?: string;
+    /**
+     * 传输模式（可选）。设置后优先于上述 direct 字段生效：
+     * - `{ type: 'endpoint', url }` — 请求转发至集成方自己的后端代理（**生产环境推荐**）
+     * - `{ type: 'custom', stream }` — 完全自定义的流式实现
+     *
+     * 不设置时回退为 direct 模式（浏览器直连模型服务商，仅限开发调试）。
+     */
+    transport?: AiTransport;
+}
+export interface ToolCallRef {
+    id: string;
+    name: string;
+    args: Record<string, any>;
+}
+export interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    tool_call_id?: string;
+    /** For assistant turns that issued tool calls — used to build the agentic history */
+    tool_calls?: ToolCallRef[];
+}
+export interface ToolDef {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, any>;
+    };
+}
+export type StreamEvent = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    args: Record<string, any>;
+} | {
+    type: 'error';
+    message: string;
+}
+/** Token usage for this model turn, when the provider reports it (M4.4). Best-effort — not every provider/proxy includes it, so consumers must treat this as optional. */
+ | {
+    type: 'usage';
+    promptTokens?: number;
+    completionTokens?: number;
+} | {
+    type: 'done';
+};
+export declare const PROVIDER_DEFAULTS: {
+    readonly openai: {
+        readonly baseUrl: "https://api.openai.com/v1";
+        readonly model: "gpt-4o";
+    };
+    readonly anthropic: {
+        readonly baseUrl: "https://api.anthropic.com";
+        readonly model: "claude-sonnet-4-6";
+    };
+};
+export declare function streamChat(messages: Message[], tools: ToolDef[], config: AiConfig, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
+export interface TestConnectionResult {
+    ok: boolean;
+    message: string;
+}
+export declare function testConnection(config: AiConfig): Promise<TestConnectionResult>;

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

@@ -0,0 +1,57 @@
+/**
+ * Rules Engine v1 — custom validation rules for workflow validation
+ *
+ * Integrators can inject business-specific rules that validate generated
+ * workflows. Rules are applied after the built-in Conductor validation,
+ * and their descriptions are injected into the system prompt so the AI
+ * generates compliant workflows from the start.
+ *
+ * Usage:
+ * ```tsx
+ * <AiWorkflowIDE
+ *   validationRules={[{
+ *     id: 'require-owner-email',
+ *     level: 'error',
+ *     description: '所有工作流必须设置 ownerEmail 字段（格式：xxx@company.com）',
+ *     validate: (def) => {
+ *       if (!def.ownerEmail?.endsWith('@company.com')) {
+ *         return [{ type: 'GLOBAL', ref: '', message: 'ownerEmail 必须为公司邮箱' }];
+ *       }
+ *       return [];
+ *     },
+ *   }]}
+ * />
+ * ```
+ */
+import type { WorkflowDef } from '../../types/conductor';
+import type { ValidationItem } from '../../types/workflow';
+export interface CustomValidationRule {
+    /** Unique rule identifier */
+    id: string;
+    /** Default severity. Individual validate() results take precedence. */
+    level?: 'error' | 'warning';
+    /**
+     * Natural-language description injected into the AI system prompt.
+     * Write it as a constraint the AI must follow when generating workflows.
+     * Example: "所有 HTTP 任务必须设置 timeoutSeconds（不超过 30 秒）"
+     */
+    description: string;
+    /**
+     * Validation function. Return an empty array if the workflow passes.
+     * Returned ValidationItems are appended to the main validation result.
+     */
+    validate: (workflowDef: WorkflowDef) => ValidationItem[];
+}
+declare class RuleEngine {
+    private rules;
+    setRules(rules: CustomValidationRule[]): void;
+    getRules(): CustomValidationRule[];
+    hasRules(): boolean;
+    runAll(workflowDef: WorkflowDef): {
+        errors: ValidationItem[];
+        warnings: ValidationItem[];
+    };
+    buildPromptSection(): string | null;
+}
+export declare const ruleEngine: RuleEngine;
+export {};

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

@@ -0,0 +1,51 @@
+/**
+ * Schema Registry v1 — task input/output schema registration
+ *
+ * Integrators can register input/output schemas for known task types.
+ * Registered schemas are injected into the AI system prompt so the model
+ * generates correct inputParameters references from the start.
+ *
+ * Usage:
+ * ```tsx
+ * <AiWorkflowIDE
+ *   taskSchemas={[{
+ *     taskName: 'send_notification',
+ *     taskType: 'SIMPLE',
+ *     description: '发送站内消息通知',
+ *     inputSchema:  { userId: 'string', message: 'string', channel: 'email|sms' },
+ *     outputSchema: { messageId: 'string', status: 'sent|failed' },
+ *   }]}
+ * />
+ * ```
+ *
+ * In inputParameters you can then reference upstream outputs:
+ *   "userId": "${approve_task.output.userId}"
+ */
+export interface TaskSchema {
+    /** Task name (SIMPLE worker name, SUB_WORKFLOW workflowName, or HTTP endpoint label) */
+    taskName: string;
+    /** Conductor task type — defaults to 'SIMPLE' */
+    taskType?: string;
+    /** Optional business-language description */
+    description?: string;
+    /**
+     * Input field schema. Keys are field names, values are type descriptions.
+     * Example: { "userId": "string", "amount": "number", "status": "pending|approved" }
+     */
+    inputSchema?: Record<string, string>;
+    /**
+     * Output field schema. Keys are field names, values are type descriptions.
+     * These are the fields available as `${taskRef.output.<field>}` in downstream tasks.
+     */
+    outputSchema?: Record<string, string>;
+}
+declare class SchemaRegistry {
+    private schemas;
+    setSchemas(schemas: TaskSchema[]): void;
+    get(taskName: string): TaskSchema | undefined;
+    getAll(): TaskSchema[];
+    hasSchemas(): boolean;
+    buildPromptSection(): string | null;
+}
+export declare const schemaRegistry: SchemaRegistry;
+export {};

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

@@ -0,0 +1,30 @@
+/**
+ * AI System Prompt — Conductor workflow expert prompt
+ *
+ * 三层定制体系（优先级从低到高）：
+ * 1. BASE_SYSTEM_PROMPT  — 本项目内置，Conductor 工作流专家角色 + 工具使用规则
+ * 2. systemPromptExtra   — 追加内容（集成方补充业务上下文，如公司名/规范）
+ * 3. systemPrompt        — 完全替换基础层（高级定制，完全控制 AI 角色和规则）
+ *
+ * BASE_SYSTEM_PROMPT 和 buildSystemPrompt 均已导出，集成方可按需复用。
+ */
+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 Conductor JSON \u5DE5\u4F5C\u6D41\u3002\n\n## \u5DE5\u5177\u4F7F\u7528\u89C4\u5219\n1. **replace_workflow** \u2014 \u7528\u4E8E\uFF1A\u4ECE\u96F6\u521B\u5EFA\u5DE5\u4F5C\u6D41\u3001\u5927\u8303\u56F4\u7ED3\u6784\u91CD\u6784\u3002\u4F20\u5165\u5B8C\u6574\u7684 WorkflowDef JSON\u3002\n2. **patch_workflow** \u2014 \u7528\u4E8E\uFF1A\u5C40\u90E8\u53D8\u66F4\uFF08\u589E/\u6539/\u5220\u4EFB\u52A1\u3001\u4FEE\u6539\u5C5E\u6027\uFF09\u3002\u6BD4 replace_workflow \u66F4\u7CBE\u51C6\u3002ops \u652F\u6301\uFF1A\n   - { op: 'add_task', task: TaskDef, afterRef?: string } \u2014 \u65B0\u589E\u4EFB\u52A1\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\n3. **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\u6CE8\u610F\uFF1Asystem prompt \u4E2D\u5DF2\u6CE8\u5165\u4E86\u5B9E\u65F6\u5DE5\u4F5C\u6D41\u4E0A\u4E0B\u6587\uFF0C\u901A\u5E38\u4E0D\u9700\u8981\u518D\u8C03\u7528\u6B64\u5DE5\u5177\u3002\n4. **validate_workflow** \u2014 \u6821\u9A8C\u5DE5\u4F5C\u6D41\u5408\u6CD5\u6027\uFF08read-only\uFF09\u3002\n5. **propose_plan** \u2014 \u5728\u6267\u884C\u590D\u6742\u591A\u6B65\u64CD\u4F5C\u524D\uFF0C\u5148\u5411\u7528\u6237\u5C55\u793A\u6267\u884C\u8BA1\u5212\u3002\u9002\u7528\u4E8E\uFF1A\u5927\u8303\u56F4\u91CD\u6784\uFF085+ \u6B65\uFF09\u3001\u62D3\u6251\u7ED3\u6784\u91CD\u5927\u53D8\u66F4\u3002\u8C03\u7528\u540E\u505C\u6B62\uFF0C\u7B49\u5F85\u7528\u6237\u786E\u8BA4\u3002\u7B80\u5355\u7684\u5355\u6B65\u64CD\u4F5C\u65E0\u9700\u5148\u63D0\u8BA1\u5212\u3002\n6. **\u4E0D\u8981**\u5728\u56DE\u590D\u4E2D\u76F4\u63A5\u8F93\u51FA\u5DE5\u4F5C\u6D41 JSON \u4EE3\u7801\u5757\uFF0C\u901A\u8FC7\u5DE5\u5177\u6267\u884C\u3002\n7. **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\n8. **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\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\u4E00\u53E5\u8BDD\u8BF4\u660E\u8981\u505A\u4EC0\u4E48\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\nSIMPLE, 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\n## \u5DE5\u4F5C\u6D41\u5EFA\u6A21\u89C4\u8303\n- \u6BCF\u4E2A\u4EFB\u52A1\u5FC5\u987B\u6709\u552F\u4E00\u7684 taskReferenceName\uFF08\u82F1\u6587\u4E0B\u5212\u7EBF\uFF0C\u5982 send_email\uFF09\n- SWITCH \u9700\u8981 caseValueParam \u6216 caseExpression\uFF0CdecisionCases \u952E\u503C\u5BF9\n- FORK_JOIN \u9700\u8981 forkTasks\uFF08\u4E8C\u7EF4\u6570\u7EC4\uFF09\u548C\u5BF9\u5E94\u7684 JOIN \u4EFB\u52A1\n- DO_WHILE \u9700\u8981 loopCondition \u548C loopOver \u6570\u7EC4\n- HTTP \u4EFB\u52A1\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";
+/**
+ * 构建完整 system prompt。
+ *
+ * @param userInput       当前用户输入（用于意图识别 + 上下文注入）
+ * @param systemPrompt    完全替换内置基础提示词（高级定制）
+ * @param systemPromptExtra  追加内容，附加在基础层之后（适合补充业务规范、公司名等）
+ * @param pendingProposalDef 待用户确认的提案 JSON（如有）。M2.2：提案不再阻塞对话输入，
+ *                           用户可以继续描述修改意见——注入此上下文后 AI 会把新消息理解为
+ *                           "基于这份提案继续调整"，而非从当前画布另起炉灶。
+ */
+export declare function buildSystemPrompt(userInput: string, workflowSnapshot: WorkflowSnapshot, libraryItems: WorkflowLibraryItem[], options?: {
+    systemPrompt?: string;
+    systemPromptExtra?: string;
+    viewMode?: ViewMode;
+    pendingProposalDef?: import('../../types/conductor').WorkflowDef;
+}): string;

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

@@ -0,0 +1,9 @@
+/**
+ * AI Tool Definitions — simplified 4-tool approach
+ *
+ * All workflow-modifying tools work at WorkflowDef JSON level.
+ * The executor applies changes as pure functions and stores a
+ * proposed WorkflowDef in aiStore for user review.
+ */
+import type { ToolDef } from './protocolAdapter';
+export declare const TOOL_DEFINITIONS: ToolDef[];

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

@@ -0,0 +1,83 @@
+/**
+ * AI Tool Executor — JSON-level workflow manipulation
+ *
+ * All modifying operations work on WorkflowDef JSON (pure functions).
+ * The result is a "proposed" def stored in aiStore for user review.
+ * Actual application to the canvas uses setWorkflow(proposedDef).
+ *
+ * This module has no store dependencies — the caller (AgentRunner) reads live
+ * workflowStore/libraryStore state and passes it in via `ToolExecutionContext`.
+ * That keeps this file pure, unit-testable without a store, and reusable headless.
+ */
+import type { WorkflowDef, TaskDef } from '../../types/conductor';
+import type { WorkflowLibraryItem, WorkflowLevel } from '../../types/workflowLibrary';
+import type { ValidationResults } from '../../types/workflow';
+export type PatchOp = {
+    op: 'add_task';
+    task: TaskDef;
+    afterRef?: string;
+} | {
+    op: 'update_task';
+    ref: string;
+    changes: Partial<TaskDef>;
+} | {
+    op: 'remove_task';
+    ref: string;
+} | {
+    op: 'update_props';
+    props: Partial<WorkflowDef>;
+} | {
+    op: 'add_switch_branch';
+    ref: string;
+    caseName: string;
+} | {
+    op: 'add_fork_branch';
+    ref: string;
+};
+/** Human-readable field-level changes for one modified task (M2.2: proposal preview card). */
+export interface TaskFieldChange {
+    ref: string;
+    changes: string[];
+}
+export interface DiffSummary {
+    added: string[];
+    modified: string[];
+    removed: string[];
+    propsChanged: boolean;
+    reordered?: boolean;
+    /** Field-level change descriptions for each modified task, e.g. "超时: 5 分钟 → 10 分钟" */
+    modifiedDetails?: TaskFieldChange[];
+}
+export interface PartialAcceptSelection {
+    added: Set<string>;
+    modified: Set<string>;
+    removed: Set<string>;
+    propsChanged: boolean;
+    reordered: boolean;
+}
+export interface ToolCallResult {
+    type: 'propose' | 'info' | 'error';
+    /** For 'propose': the new WorkflowDef to show in ReviewBar */
+    proposed?: WorkflowDef;
+    /** For 'propose': human-readable change summary */
+    diff?: DiffSummary;
+    /** For 'propose': inferred level based on sub-workflow references (L1/L2/L3) */
+    inferredLevel?: WorkflowLevel;
+    /** For 'info'/'error': text to append to chat */
+    text?: string;
+}
+/** Live state the caller (AgentRunner) gathers from workflowStore/libraryStore for each tool call. */
+export interface ToolExecutionContext {
+    workflowDef: WorkflowDef | null;
+    validationResults: ValidationResults;
+    libraryItems: WorkflowLibraryItem[];
+}
+export declare function applyPatch(def: WorkflowDef, ops: PatchOp[]): WorkflowDef;
+export declare function computeDiff(before: WorkflowDef | null, after: WorkflowDef): DiffSummary;
+export declare function executeToolCall(toolName: string, 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.
+ */
+export declare function applyPartialProposal(currentDef: WorkflowDef, proposedDef: WorkflowDef, diff: DiffSummary, selection: PartialAcceptSelection): WorkflowDef;
+export declare function describeDiff(diff: DiffSummary): string;

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

@@ -0,0 +1,38 @@
+/**
+ * Tool Registry v1 — extensible custom tool integration
+ *
+ * Integrators can register custom tools that the AI can call.
+ * Custom tools appear alongside built-in tools in the agentic loop.
+ *
+ * Usage:
+ * ```tsx
+ * <AiWorkflowIDE
+ *   customTools={[{
+ *     definition: { type: 'function', function: { name: 'query_cmdb', ... } },
+ *     execute: async (args) => JSON.stringify(await fetchCmdb(args.query)),
+ *   }]}
+ * />
+ * ```
+ */
+import type { ToolDef } from './protocolAdapter';
+export interface CustomTool {
+    /** OpenAI-compatible function definition (used for both OpenAI and Anthropic) */
+    definition: ToolDef;
+    /**
+     * Execution function.
+     * Must return a string (or Promise<string>) to be sent back to the model as a tool result.
+     * Throw an Error to surface a failure message to the model.
+     */
+    execute: (args: Record<string, any>) => string | Promise<string>;
+}
+export declare class ToolRegistry {
+    private tools;
+    register(tool: CustomTool): void;
+    unregister(name: string): void;
+    get(name: string): CustomTool | undefined;
+    getAll(): CustomTool[];
+    getDefinitions(): ToolDef[];
+    setTools(tools: CustomTool[]): void;
+    has(name: string): boolean;
+}
+export declare const toolRegistry: ToolRegistry;

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

@@ -0,0 +1,58 @@
+/**
+ * AI Transport — 传输层反转
+ *
+ * 背景：默认的 direct 模式让 API Key 直接留存在终端用户浏览器中，直连大模型服务商
+ * （参见 protocolAdapter.ts 的 streamOpenAI/streamAnthropic）。这仅适合开发调试，
+ * 生产环境应通过集成方自己的后端转发模型请求，密钥、计费、限流、审计都留在后端完成。
+ *
+ * 本文件提供两种反转方案：
+ * - `endpoint`：把统一的 AgentRequest POST 给集成方后端，后端以 SSE 帧协议回传 StreamEvent。
+ *   后端参考实现（Node/Express，约 30 行）：
+ *
+ *   ```js
+ *   app.post('/api/ai/chat', async (req, res) => {
+ *     res.setHeader('Content-Type', 'text/event-stream');
+ *     res.setHeader('Cache-Control', 'no-cache');
+ *     res.setHeader('Connection', 'keep-alive');
+ *     // req.body = { messages, tools, meta } —— 按需转发给 OpenAI/Anthropic，
+ *     // 或直接复用本仓库的 streamOpenAI/streamAnthropic 实现（Node 端可直接 import 使用）。
+ *     for await (const event of callYourLlmProvider(req.body)) {
+ *       res.write(`data: ${JSON.stringify(event)}\n\n`);
+ *     }
+ *     res.end();
+ *   });
+ *   ```
+ *
+ * - `custom`：完全自定义的流式函数，适合已有网关/SDK 的集成方直接接入。
+ *
+ * 不设置 `transport` 时，AiConfig 的 provider/apiKey/baseUrl/model 视为 direct 模式
+ * （向后兼容现状），仅建议用于开发调试或内部可信环境。
+ */
+import type { Message, ToolDef, StreamEvent } from './protocolAdapter';
+/** endpoint / custom 传输统一入参：与 direct 模式内部构造的请求体等价 */
+export interface AgentRequest {
+    messages: Message[];
+    tools: ToolDef[];
+    meta?: {
+        sessionId?: string;
+    };
+}
+export type AiTransport = {
+    type: 'endpoint';
+    /** 集成方后端代理地址，POST AgentRequest，响应为 `data: <JSON StreamEvent>\n\n` 的 SSE 流 */
+    url: string;
+    /** 附加请求头（如后端会话鉴权 Cookie/Token 之外的自定义头） */
+    headers?: Record<string, string>;
+} | {
+    type: 'custom';
+    /** 完全自定义的流式实现，直接产出统一的 StreamEvent */
+    stream: (req: AgentRequest, signal: AbortSignal) => AsyncIterable<StreamEvent>;
+};
+/**
+ * endpoint 模式：POST AgentRequest，解析 SSE 帧（`data: <JSON>\n\n`）为 StreamEvent。
+ * 帧解析逻辑与 protocolAdapter 的 OpenAI/Anthropic 流解析一致地处理跨 chunk 边界，
+ * 避免 JSON 被截断在两次 read() 之间。
+ */
+export declare function streamEndpoint(transport: Extract<AiTransport, {
+    type: 'endpoint';
+}>, req: AgentRequest, signal?: AbortSignal): AsyncGenerator<StreamEvent>;