@steerable/agent-shell-web 0.6.50 → 0.6.51

package/src/components/chat/orchestration-flow-model.ts

@@ -0,0 +1,336 @@
+/**
+ * 多智能体协同编排模型（Orchestration Flow Model）
+ *
+ * 将 CoreLoop 编排六件套（agent_spawn / agent_wait / agent_send / agent_interrupt / agent_close / agent_list）
+ * 以及 SSE agent.child 生命周期事件聚合成面向用户的 DAG 流程图与 Todo 式状态模型。
+ */
+
+import type { ChildInfo } from './orchestration-children-model';
+import { parseToolEnvelope } from './executed-actions-model';
+
+export const ORCHESTRATION_TOOL_NAMES = [
+  'agent_spawn',
+  'agent_wait',
+  'agent_send',
+  'agent_interrupt',
+  'agent_close',
+  'agent_list',
+] as const;
+
+export type OrchestrationToolName = (typeof ORCHESTRATION_TOOL_NAMES)[number];
+
+export function isOrchestrationTool(toolName: string): toolName is OrchestrationToolName {
+  return (ORCHESTRATION_TOOL_NAMES as readonly string[]).includes(toolName);
+}
+
+export type OrchestrationNodeStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'interrupted'
+  | 'closed';
+
+export interface OrchestrationSteer {
+  message: string;
+  delivery?: string;
+}
+
+export interface OrchestrationChildNode {
+  childId: string;
+  task: string;
+  toolFilter?: string[];
+  status: OrchestrationNodeStatus;
+  answer?: string;
+  steers: OrchestrationSteer[];
+  interrupted?: boolean;
+  closed?: boolean;
+  recordId?: string;
+  error?: string;
+  spawnActionIndex?: number;
+  waitActionIndex?: number;
+}
+
+export interface OrchestrationFlowData {
+  nodes: OrchestrationChildNode[];
+  totalCount: number;
+  completedCount: number;
+  runningCount: number;
+  failedCount: number;
+  interruptedCount: number;
+  closedCount: number;
+  isAllCompleted: boolean;
+  hasActive: boolean;
+  summaryCopy: string;
+}
+
+interface ActionLike {
+  tool: string;
+  arguments?: unknown;
+  result?: unknown;
+}
+
+function safeParseJson(value: unknown): Record<string, unknown> | null {
+  if (!value) return null;
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          return parsed as Record<string, unknown>;
+        }
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+export function extractOrchestrationFlow(
+  actions?: readonly ActionLike[] | null,
+  children?: readonly ChildInfo[] | null,
+): OrchestrationFlowData | null {
+  const nodeMap = new Map<string, OrchestrationChildNode>();
+
+  // 1. 先用 SSE 累积的 ChildInfo 占位（实时性最高，包含 live 状态与 recordId）
+  if (children && children.length > 0) {
+    for (const c of children) {
+      if (!c.childId) continue;
+      nodeMap.set(c.childId, {
+        childId: c.childId,
+        task: c.task || '',
+        status: (c.status as OrchestrationNodeStatus) || 'running',
+        recordId: c.recordId,
+        steers: [],
+      });
+    }
+  }
+
+  // 2. 扫描 actions 里的编排六件套
+  const actionList = actions ?? [];
+  let hasOrchAction = false;
+
+  actionList.forEach((action, actionIdx) => {
+    if (!isOrchestrationTool(action.tool)) return;
+    hasOrchAction = true;
+
+    const rawArgs = safeParseJson(action.arguments) ?? {};
+    const envelope = parseToolEnvelope(action.result);
+    const innerMsg = safeParseJson(envelope.message);
+    const innerData = safeParseJson(envelope.fields?.data);
+
+    if (action.tool === 'agent_spawn') {
+      const task = typeof rawArgs.task === 'string' ? rawArgs.task.trim() : '';
+      const rawFilter = Array.isArray(rawArgs.toolFilter) ? rawArgs.toolFilter.map(String) : undefined;
+
+      // childId 优先从结果里提取
+      const childId =
+        (typeof envelope.fields.childId === 'string' ? envelope.fields.childId : null) ??
+        (typeof innerData?.childId === 'string' ? innerData.childId : null) ??
+        (typeof innerMsg?.childId === 'string' ? innerMsg.childId : null) ??
+        `spawn-${actionIdx}`;
+
+      let node = nodeMap.get(childId);
+      if (!node) {
+        node = {
+          childId,
+          task,
+          toolFilter: rawFilter,
+          status: 'running',
+          steers: [],
+          spawnActionIndex: actionIdx,
+        };
+        nodeMap.set(childId, node);
+      } else {
+        if (!node.task && task) node.task = task;
+        if (!node.toolFilter && rawFilter) node.toolFilter = rawFilter;
+        if (node.spawnActionIndex === undefined) node.spawnActionIndex = actionIdx;
+      }
+
+      if (envelope.success === false || envelope.error) {
+        node.status = 'failed';
+        node.error = envelope.error || '派发失败';
+      }
+    } else if (action.tool === 'agent_wait') {
+      const childId = typeof rawArgs.childId === 'string' ? rawArgs.childId.trim() : '';
+      if (childId) {
+        let node = nodeMap.get(childId);
+        if (!node) {
+          node = {
+            childId,
+            task: '',
+            status: 'running',
+            steers: [],
+            waitActionIndex: actionIdx,
+          };
+          nodeMap.set(childId, node);
+        } else {
+          node.waitActionIndex = actionIdx;
+        }
+
+        const waitStatus =
+          (typeof innerData?.status === 'string' ? innerData.status : null) ??
+          (typeof innerMsg?.status === 'string' ? innerMsg.status : null);
+        const answer =
+          (typeof innerMsg?.answer === 'string' ? innerMsg.answer : null) ??
+          (typeof innerData?.answer === 'string' ? innerData.answer : null);
+
+        if (answer) {
+          node.answer = answer;
+        }
+
+        if (waitStatus === 'completed') {
+          node.status = 'completed';
+        } else if (waitStatus === 'failed' || waitStatus === 'error' || envelope.success === false) {
+          node.status = 'failed';
+          node.error = envelope.error || '执行失败';
+        } else if (waitStatus === 'running') {
+          node.status = 'running';
+        }
+      }
+    } else if (action.tool === 'agent_send') {
+      const childId = typeof rawArgs.childId === 'string' ? rawArgs.childId.trim() : '';
+      const message = typeof rawArgs.message === 'string' ? rawArgs.message.trim() : '';
+      if (childId && message) {
+        const node = nodeMap.get(childId);
+        if (node) {
+          const delivery =
+            (typeof innerData?.delivery === 'string' ? innerData.delivery : null) ??
+            (typeof innerMsg?.delivery === 'string' ? innerMsg.delivery : null);
+          node.steers.push({ message, delivery: delivery ?? undefined });
+        }
+      }
+    } else if (action.tool === 'agent_interrupt') {
+      const childId = typeof rawArgs.childId === 'string' ? rawArgs.childId.trim() : '';
+      if (childId) {
+        const node = nodeMap.get(childId);
+        if (node) {
+          node.interrupted = true;
+          node.status = 'interrupted';
+        }
+      }
+    } else if (action.tool === 'agent_close') {
+      const childId = typeof rawArgs.childId === 'string' ? rawArgs.childId.trim() : '';
+      if (childId) {
+        const node = nodeMap.get(childId);
+        if (node) {
+          node.closed = true;
+          if (node.status !== 'completed') {
+            node.status = 'closed';
+          }
+        }
+      }
+    } else if (action.tool === 'agent_list') {
+      const childrenArr = Array.isArray(innerMsg?.children) ? innerMsg.children : null;
+      if (childrenArr) {
+        for (const rawChild of childrenArr) {
+          if (rawChild && typeof rawChild === 'object') {
+            const cid = typeof rawChild.childId === 'string' ? rawChild.childId : '';
+            if (!cid) continue;
+            let node = nodeMap.get(cid);
+            if (!node) {
+              node = {
+                childId: cid,
+                task: typeof rawChild.task === 'string' ? rawChild.task : '',
+                status: (rawChild.status as OrchestrationNodeStatus) || 'running',
+                answer: typeof rawChild.answer === 'string' ? rawChild.answer : undefined,
+                steers: [],
+              };
+              nodeMap.set(cid, node);
+            } else {
+              if (!node.task && rawChild.task) node.task = String(rawChild.task);
+              if (!node.answer && rawChild.answer) node.answer = String(rawChild.answer);
+            }
+          }
+        }
+      }
+    }
+  });
+
+  if (!hasOrchAction && (!children || children.length === 0)) {
+    return null;
+  }
+
+  const nodes = Array.from(nodeMap.values());
+  if (nodes.length === 0) return null;
+
+  const totalCount = nodes.length;
+  const completedCount = nodes.filter((n) => n.status === 'completed').length;
+  const runningCount = nodes.filter((n) => n.status === 'running' || n.status === 'pending').length;
+  const failedCount = nodes.filter((n) => n.status === 'failed').length;
+  const interruptedCount = nodes.filter((n) => n.status === 'interrupted').length;
+  const closedCount = nodes.filter((n) => n.status === 'closed').length;
+  const isAllCompleted = totalCount > 0 && completedCount === totalCount;
+  const hasActive = runningCount > 0;
+
+  let summaryCopy = '';
+  if (isAllCompleted) {
+    summaryCopy = `${completedCount}/${totalCount} 全部完成`;
+  } else if (hasActive) {
+    summaryCopy = `协同执行中 (${completedCount}/${totalCount} 完成)...`;
+  } else {
+    summaryCopy = `${completedCount} 完成 · ${totalCount - completedCount} 结束 (${totalCount} 个子任务)`;
+  }
+
+  return {
+    nodes,
+    totalCount,
+    completedCount,
+    runningCount,
+    failedCount,
+    interruptedCount,
+    closedCount,
+    isAllCompleted,
+    hasActive,
+    summaryCopy,
+  };
+}
+
+function actionsFromTimeline(blocks?: ReadonlyArray<{ type: string; actions?: unknown[] }>): ActionLike[] {
+  if (!blocks) return [];
+  const actions: ActionLike[] = [];
+  for (const block of blocks) {
+    if (block.type === 'tools' && Array.isArray(block.actions)) {
+      actions.push(...(block.actions as ActionLike[]));
+    }
+  }
+  return actions;
+}
+
+/**
+ * 提取当前打开对话中最新一轮的编排流程。
+ * 正在流式/执行中的回合优先；历史回合倒序寻找最新的一次编排。
+ */
+export function resolveLatestSessionOrchestrationFlow(input: {
+  messages: Array<{ id: string }>;
+  executedActionsByMessageId?: Record<string, ActionLike[]>;
+  currentTurnActions?: ActionLike[];
+  currentTurnChildren?: ChildInfo[];
+  orchestrationChildrenByMessageId?: Record<string, ChildInfo[]>;
+  timelineByMessageId?: Record<string, Array<{ type: string; actions?: unknown[] }>>;
+  currentTurnTimeline?: Array<{ type: string; actions?: unknown[] }>;
+}): OrchestrationFlowData | null {
+  // 1. 优先实时回合
+  const liveActions =
+    input.currentTurnActions ?? actionsFromTimeline(input.currentTurnTimeline);
+  const liveFlow = extractOrchestrationFlow(liveActions, input.currentTurnChildren);
+  if (liveFlow && liveFlow.totalCount > 0) return liveFlow;
+
+  // 2. 倒序历史回合
+  for (let i = input.messages.length - 1; i >= 0; i -= 1) {
+    const id = input.messages[i].id;
+    const actions =
+      input.executedActionsByMessageId?.[id] ??
+      actionsFromTimeline(input.timelineByMessageId?.[id]);
+    const children = input.orchestrationChildrenByMessageId?.[id];
+    const flow = extractOrchestrationFlow(actions, children);
+    if (flow && flow.totalCount > 0) return flow;
+  }
+
+  return null;
+}

package/src/components/settings/OrchestrationSettingsPanel.tsx

@@ -0,0 +1,67 @@
+import { LuGitFork } from 'react-icons/lu';
+import { useOrchestrationSetting } from '@/lib/orchestration-settings';
+
+/**
+ * OrchestrationSettingsPanel — 多智能体协同编排设置面板。
+ * 默认开启。用户可手动关闭或再次开启，变更实时持久化并影响后续对话请求。
+ */
+export function OrchestrationSettingsPanel() {
+  const [enabled, setEnabled] = useOrchestrationSetting();
+
+  return (
+    <div
+      className="space-y-2.5 rounded-agent-md border border-agent-border bg-agent-card p-3"
+      data-testid="orchestration-settings-panel"
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="space-y-1">
+          <div className="flex items-center gap-1.5 text-xs font-semibold text-agent-foreground">
+            <LuGitFork className="h-3.5 w-3.5 text-violet-600 dark:text-violet-400" />
+            <span>多智能体协同编排 (Fork-Join)</span>
+          </div>
+          <p className="text-xs leading-relaxed text-agent-muted-foreground">
+            允许主智能体通过派生子任务（agent_spawn）并行推理计算，并在输入框上方呈现流程图与实时协同进度看板。
+          </p>
+        </div>
+
+        {/* 开关 Radio Group / Toggle */}
+        <div
+          className="flex shrink-0 rounded-full border border-agent-border bg-agent-canvas p-0.5"
+          role="radiogroup"
+          aria-label="多智能体协同编排功能开关"
+        >
+          <button
+            type="button"
+            role="radio"
+            aria-checked={enabled}
+            onClick={() => setEnabled(true)}
+            className={[
+              'h-6 rounded-full px-2.5 text-[11px] font-medium transition-colors',
+              enabled
+                ? 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-300 shadow-2xs'
+                : 'text-agent-muted-foreground hover:text-agent-foreground',
+            ].join(' ')}
+          >
+            开启
+          </button>
+          <button
+            type="button"
+            role="radio"
+            aria-checked={!enabled}
+            onClick={() => setEnabled(false)}
+            className={[
+              'h-6 rounded-full px-2.5 text-[11px] font-medium transition-colors',
+              !enabled
+                ? 'bg-agent-foreground/10 text-agent-foreground shadow-2xs'
+                : 'text-agent-muted-foreground hover:text-agent-foreground',
+            ].join(' ')}
+          >
+            关闭
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default OrchestrationSettingsPanel;

package/src/components/settings/SettingsNavMenu.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+
+export interface SettingsNavItem {
+  id: string;
+  label: string;
+  Icon: React.ComponentType<{ className?: string }>;
+}
+
+export function SettingsNavMenu({
+  items,
+  activeId,
+  onSelect,
+}: {
+  items: SettingsNavItem[];
+  activeId: string | null;
+  onSelect: (id: string) => void;
+}) {
+  if (items.length === 0) return null;
+
+  return (
+    <aside
+      className="sticky top-0 h-fit w-44 shrink-0 py-1 select-none"
+      data-testid="settings-side-nav"
+      aria-label="设置目录导航"
+    >
+      <div className="mb-2 px-2.5 text-[11px] font-semibold tracking-wider text-agent-muted-foreground uppercase">
+        设置导航
+      </div>
+      <nav className="space-y-0.5">
+        {items.map((item) => {
+          const isActive = activeId === item.id;
+          return (
+            <button
+              key={item.id}
+              type="button"
+              data-testid={`settings-nav-item-${item.id}`}
+              onClick={() => onSelect(item.id)}
+              className={[
+                'flex w-full items-center gap-2 rounded-agent-sm px-2.5 py-1.5 text-left text-xs transition-colors',
+                isActive
+                  ? 'bg-agent-foreground/10 font-semibold text-agent-foreground'
+                  : 'text-agent-muted-foreground hover:bg-agent-foreground/5 hover:text-agent-foreground',
+              ].join(' ')}
+            >
+              <item.Icon className={`h-3.5 w-3.5 shrink-0 ${isActive ? 'text-agent-foreground' : 'text-agent-muted-foreground'}`} />
+              <span className="truncate">{item.label}</span>
+            </button>
+          );
+        })}
+      </nav>
+    </aside>
+  );
+}
+
+export default SettingsNavMenu;

package/src/lib/orchestration-settings.ts

@@ -0,0 +1,58 @@
+import { useEffect, useState } from 'react';
+
+export const ORCHESTRATION_SETTING_STORAGE_KEY = 'steerable.orchestration.enabled';
+
+const CHANGE_EVENT = 'steerable:orchestration-setting-changed';
+
+/**
+ * 读取多智能体协同编排功能开关，默认开启 (true)。
+ */
+export function isOrchestrationSettingEnabled(): boolean {
+  if (typeof localStorage === 'undefined') return true;
+  const stored = localStorage.getItem(ORCHESTRATION_SETTING_STORAGE_KEY);
+  if (stored === null) return true; // 默认开启
+  return stored !== 'false' && stored !== '0';
+}
+
+/**
+ * 持久化多智能体协同编排开关到 localStorage 并广播变更。
+ */
+export function persistOrchestrationSetting(enabled: boolean): void {
+  if (typeof localStorage === 'undefined') return;
+  localStorage.setItem(ORCHESTRATION_SETTING_STORAGE_KEY, enabled ? 'true' : 'false');
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT, { detail: enabled }));
+  }
+}
+
+/**
+ * 响应式 hook：订阅并切换编排功能开关。
+ */
+export function useOrchestrationSetting(): [boolean, (enabled: boolean) => void] {
+  const [enabled, setEnabled] = useState<boolean>(() => isOrchestrationSettingEnabled());
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const handler = (e: Event) => {
+      const custom = e as CustomEvent<boolean>;
+      if (typeof custom.detail === 'boolean') {
+        setEnabled(custom.detail);
+      } else {
+        setEnabled(isOrchestrationSettingEnabled());
+      }
+    };
+    window.addEventListener(CHANGE_EVENT, handler);
+    window.addEventListener('storage', handler);
+    return () => {
+      window.removeEventListener(CHANGE_EVENT, handler);
+      window.removeEventListener('storage', handler);
+    };
+  }, []);
+
+  const update = (next: boolean) => {
+    setEnabled(next);
+    persistOrchestrationSetting(next);
+  };
+
+  return [enabled, update];
+}

package/src/pages/AgentPage.tsx

@@ -61,6 +61,7 @@ import {
   setPendingFirstMessage,
   takePendingFirstMessage,
 } from "@/lib/pending-first-message";
+import { isOrchestrationSettingEnabled } from "@/lib/orchestration-settings";
 import { BRAND_NAME, pickDefaultAgentId } from "@/brand";
 import {
   appendAttachmentRefs,
@@ -869,6 +870,7 @@ function AgentChatView({
         ...(modelOverride ? { model: modelOverride } : {}),
         ...(effortOverride ? { reasoningEffort: effortOverride } : {}),
         ...(execPolicy === "full" ? { execPolicy: "full" } : {}),
+        orchestration: isOrchestrationSettingEnabled(),
       };
       return sendUserMessage({
         ...input,