跳转到内容

前端 SDK 导出:AGENT_CONVERSATION_SERVICE – AlignBottomIcon

本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/frontend/extension-api。

返回接口索引

AGENT_CONVERSATION_SERVICE · ASSISTANT_SETUP_HINT · ASSISTANT_SETUP_TOOLTIP · ActivityIcon · AdaptiveRatioIcon · AdjustmentIcon · AgentAssistantSettingsLink · AgentConversationActiveTurn · AgentConversationRemote · AgentConversationResult · AgentConversationService · AgentConversationServiceHandle · AgentConversationSnapshotView · AgentConversationSubmitInput · AgentConversationSubmitResult · AgentConversationView · AgentDetailAction · AgentDetailActionEmphasis · AgentDetailStatus · AgentIcon · AlertDialog · AlertDialogProps · AlertDialogSurface · AlignBottomIcon

AGENT_CONVERSATION_SERVICE

宿主 Agent 会话 capability key(由 task-execution plugin 提供) 。

宿主生成的会话详情入口与详情面板都经此读取宿主拥有的会话服务;业务生成扩展(如 ChatGPT)只提供 adapter,不提供本 key。optional 缺失时不显示详情入口,普通生成继续工作。

export const AGENT_CONVERSATION_SERVICE: "agentConversationService";

ASSISTANT_SETUP_HINT

export const ASSISTANT_SETUP_HINT: "尚未配置助手。连接一个助手即可开始,创作描述会保留在这里。";

ASSISTANT_SETUP_TOOLTIP

export const ASSISTANT_SETUP_TOOLTIP: "尚未配置助手,点击这里配置。";

ActivityIcon

export const ActivityIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

AdaptiveRatioIcon

画幅「自适应」(执行面板比例选择器左侧的四角取景框)。

export const AdaptiveRatioIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

AdjustmentIcon

export const AdjustmentIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

export function AgentAssistantSettingsLink({ onOpen }: { onOpen: () => void; }): React.JSX.Element;

AgentConversationActiveTurn

宿主会话读模型快照(生成面板与详情共用)。

active 是最后一次提交/查询得到的对话身份,用于状态区摘要与详情定位;detail 是详情面板 打开的权威快照(未打开时 null)。前端只持读模型,事实源在后端。

export type AgentConversationActiveTurn = {
conversationId: string;
requestId: string;
turn: ConversationTurn;
};

关联类型:ConversationTurn

AgentConversationRemote

export type AgentConversationRemote = {
listServiceConnections?: () => Promise<AgentConversationResult<import("@woohaa3/contracts").ServiceConnectionDirectory>>;
manageServiceConnection?: (input: import("@woohaa3/contracts").ServiceConnectionManagement) => Promise<AgentConversationResult<{
connection: import("@woohaa3/contracts").ServiceConnectionView;
}>>;
catalog: (adapterId?: string) => Promise<AgentConversationResult<AgentCatalogResponse>>;
roles?: (adapterId?: string) => Promise<AgentConversationResult<{
roles: readonly import("@woohaa3/contracts").AgentRoleDescriptor[];
}>>;
listConnections: (adapterId?: string) => Promise<AgentConversationResult<{
connections: AgentConnectionView[];
}>>;
mcpStatus: () => Promise<AgentConversationResult<AgentMcpStatusResponse>>;
list: (canvasId: string) => Promise<AgentConversationResult<{
conversations: ConversationSummary[];
}>>;
create: (input: {
contextKey?: string;
canvasId: string;
adapterId?: string;
title?: string;
nodeId?: string;
connectionId?: string;
}) => Promise<AgentConversationResult<{
conversation: ConversationSummary;
}>>;
findForTarget: (canvasId: string, nodeId: string, connectionId?: string, contextKey?: string) => Promise<AgentConversationResult<{
conversation: ConversationSummary | null;
}>>;
clearContext: (canvasId: string, nodeId: string) => Promise<AgentConversationResult<{
ok: true;
cleared: number;
}>>;
switchConnection: (input: {
canvasId: string;
nodeId: string;
connectionId: string;
}) => Promise<AgentConversationResult<{
ok: true;
cleared: number;
}>>;
read: (conversationId: string, cursor?: number) => Promise<AgentConversationResult<ConversationSnapshot>>;
accept: (conversationId: string, input: {
requestId: string;
entry: AgentEntryIntent;
}) => Promise<AgentConversationResult<{
conversation: ConversationSummary;
turn: ConversationTurn;
reused: boolean;
}>>;
acceptImageDirectorScene?: (conversationId: string, input: {
requestId: string;
entry: AgentEntryIntent;
}) => Promise<AgentConversationResult<{
conversation: ConversationSummary;
turn: ConversationTurn;
reused: boolean;
}>>;
query: (requestId: string) => Promise<AgentConversationResult<{
conversation: ConversationSummary;
turn: ConversationTurn;
snapshot: ConversationSnapshot;
}>>;
locate: (runId: string) => Promise<AgentConversationResult<{
conversation: ConversationSummary;
turn: ConversationTurn;
snapshot: ConversationSnapshot;
}>>;
retryTextSave?: (requestId: string) => Promise<AgentConversationResult<{
turn: ConversationTurn;
}>>;
cancel: (requestId: string) => Promise<AgentConversationResult<{
ok: true;
}>>;
link: (requestId: string, input: {
runId?: string;
taskId?: string;
}) => Promise<AgentConversationResult<{
turn: ConversationTurn;
}>>;
skillStepByNode: (canvasId: string, nodeId: string) => Promise<AgentConversationResult<{
step: import("@woohaa3/contracts").SkillMediaStepView | null;
}>>;
skillSteps: (canvasId: string, limit?: number) => Promise<AgentConversationResult<{
steps: import("@woohaa3/contracts").SkillMediaStepView[];
}>>;
skillStepDetail: (input: {
canvasId: string;
skillRunId: string;
stepId: string;
after?: number;
}) => Promise<AgentConversationResult<{
step: import("@woohaa3/contracts").SkillMediaStepView;
events: Array<import("@woohaa3/contracts").SkillStepUpdatedEvent & {
sequence: number;
}>;
cursor: number;
resetRequired: boolean;
}>>;
cancelSkillStep: (input: {
canvasId: string;
skillRunId: string;
stepId: string;
}) => Promise<AgentConversationResult<{
step: import("@woohaa3/contracts").SkillMediaStepView;
state: "cancel-requested" | "already-terminal";
}>>;
regenerateSkillStep: (input: {
canvasId: string;
skillRunId: string;
stepId: string;
requestId: string;
prompt?: string;
modelKey?: string;
parameters?: Record<string, unknown>;
}) => Promise<AgentConversationResult<{
step: import("@woohaa3/contracts").SkillMediaStepView;
runId: string;
}>>;
};

关联类型:AgentConversationResult · ServiceConnectionDirectory · ServiceConnectionManagement · ServiceConnectionView · AgentCatalogResponse · AgentRoleDescriptor · AgentConnectionView · AgentMcpStatusResponse · ConversationSummary · ConversationSnapshot · AgentEntryIntent · ConversationTurn · SkillMediaStepView · SkillStepUpdatedEvent

成员说明:

  • roles:只读角色目录与能力匹配。 通用界面据此在提交前展示必要能力缺失;查询本身不准备、不推理。
  • listConnections:该 owner 可见的来源连接。 只读;adapterId 提供时只返回该来源的连接。不缓存 capability 结果。
  • mcpStatus:内置 MCP 真实发现 + 外部连接指引(宿主投影;复制不等于外部已连接)。
  • findForTarget:该节点当前会话(一个节点复用一条;design D8)。无则 conversation: null(调用方据此新建)。 connectionId 提供时只返回该来源连接下的会话。
  • clearContext:清空节点上下文:解除关联、归档旧会话(不删除历史)。
  • switchConnection:显式切换来源连接:解除目标关联、归档旧会话(保留历史)。活动回合由后端拒绝 。
  • locate:按领域运行关联定位确切回合(活动/历史 Agent 记录 → 确切 request/run) 。 只匹配已显式关联的 runId,绝不按 nodeId 跳到最近会话;无关联时返回 not-found 让调用方 回退到原任务详情。只读,不 accept/dispatch。
  • skillStepByNode:Skill 媒体步骤续接。 只读快照与事件;停止/重新生成走独立写入口,不重新提交 Agent 回合。

AgentConversationResult

会话操作结果:失败携带稳定错误码与可读原因。

export type AgentConversationResult<T> = {
ok: true;
value: T;
} | {
ok: false;
code: string;
error: string;
};

AgentConversationService

宿主会话服务(前端 capability)。

前端只持有草稿/展开/滚动;会话事实源在后端。所有方法只读或显式接受回合,打开/查询/ 关闭绝不重新 accept 或 dispatch。

export type AgentConversationService = AgentConversationView & {
serviceConnectionDirectory?: () => Promise<AgentConversationResult<ServiceConnectionDirectory>>;
manageServiceConnection?: (input: ServiceConnectionManagement) => Promise<AgentConversationResult<ServiceConnectionView>>;
listServiceConnections?: () => Promise<AgentConversationResult<ServiceConnectionView[]>>;
getDataScopeId?: () => string | null;
invalidateDirectory: () => void;
catalog: (adapterId?: string) => Promise<AgentConversationResult<AgentCatalogResponse>>;
mcpStatus: () => Promise<AgentConversationResult<AgentMcpStatusResponse>>;
listConversations: (canvasId: string) => Promise<AgentConversationResult<ConversationSummary[]>>;
findConversationForTarget: (input: {
contextKey?: string;
canvasId: string;
nodeId: string;
connectionId?: string;
}) => Promise<AgentConversationResult<{
conversation: ConversationSummary | null;
}>>;
clearContext: (input: {
canvasId: string;
nodeId: string;
}) => Promise<AgentConversationResult<{
cleared: number;
}>>;
listConnections: (adapterId?: string) => Promise<AgentConversationResult<AgentConnectionView[]>>;
switchConnection: (input: {
canvasId: string;
nodeId: string;
connectionId: string;
}) => Promise<AgentConversationResult<{
cleared: number;
}>>;
readConversation: (conversationId: string, cursor?: number) => Promise<AgentConversationResult<ConversationSnapshot>>;
submitTurn: (input: AgentConversationSubmitInput & {
requestId: string;
}) => Promise<AgentConversationResult<AgentConversationSubmitResult>>;
submitImageDirectorScene?: (input: AgentConversationSubmitInput & {
requestId: string;
}) => Promise<AgentConversationResult<AgentConversationSubmitResult>>;
queryTurn: (requestId: string) => Promise<AgentConversationResult<{
conversation: ConversationSummary;
turn: ConversationTurn;
snapshot: ConversationSnapshot;
}>>;
locateTurnByRun: (runId: string) => Promise<AgentConversationResult<{
conversation: ConversationSummary;
turn: ConversationTurn;
snapshot: ConversationSnapshot;
}>>;
retryTextSave?: (requestId: string) => Promise<AgentConversationResult<{
turn: ConversationTurn;
}>>;
cancelTurn: (requestId: string) => Promise<AgentConversationResult<{
ok: true;
}>>;
linkRun: (requestId: string, input: {
runId?: string;
taskId?: string;
}) => Promise<AgentConversationResult<{
turn: ConversationTurn;
}>>;
skillStep: (input: {
canvasId: string;
nodeId: string;
}) => Promise<AgentConversationResult<{
step: SkillMediaStepView | null;
}>>;
skillSteps: (input: {
canvasId: string;
limit?: number;
}) => Promise<AgentConversationResult<{
steps: SkillMediaStepView[];
}>>;
skillStepDetail: (input: {
canvasId: string;
skillRunId: string;
stepId: string;
after?: number;
}) => Promise<AgentConversationResult<{
step: SkillMediaStepView;
events: Array<SkillStepUpdatedEvent & {
sequence: number;
}>;
cursor: number;
resetRequired: boolean;
}>>;
cancelSkillStep: (input: {
canvasId: string;
skillRunId: string;
stepId: string;
}) => Promise<AgentConversationResult<{
step: SkillMediaStepView;
state: "cancel-requested" | "already-terminal";
}>>;
regenerateSkillStep: (input: {
canvasId: string;
skillRunId: string;
stepId: string;
requestId: string;
prompt?: string;
modelKey?: string;
parameters?: Record<string, unknown>;
}) => Promise<AgentConversationResult<{
step: SkillMediaStepView;
runId: string;
}>>;
};

关联类型:AgentConversationView · AgentConversationResult · ServiceConnectionDirectory · ServiceConnectionManagement · ServiceConnectionView · AgentCatalogResponse · AgentMcpStatusResponse · ConversationSummary · AgentConnectionView · ConversationSnapshot · AgentConversationSubmitInput · AgentConversationSubmitResult · ConversationTurn · SkillMediaStepView · SkillStepUpdatedEvent

成员说明:

  • invalidateDirectory:配置保存后清除连接/模型目录请求缓存;不改变会话事实或草稿。
  • catalog:读取 adapter 授权/能力/账户目录(真实状态,不自动换模型)。
  • mcpStatus:内置 MCP 真实发现 + 外部连接指引(宿主投影) 。 builtin.ready 只来自后端 executed initialize/源码声明;external 只是当前 origin 的 Streamable HTTP URL,复制地址不等于外部客户端已连接。
  • listConversations:当前画布的会话列表(有界)。
  • findConversationForTarget:按生成目标节点查找该节点当前会话(一个节点复用一条;design D8)。只读。 无则 conversation: null(调用方据此新建);不改变导航或读模型。 connectionId 提供时只返回该来源连接下的会话。
  • clearContext:清空节点上下文:解除该节点与当前会话的关联(归档旧会话,不删除历史;design D8)。 随后该节点提交将新建会话;同时清理本地读模型中该会话的 active/detail。
  • listConnections:该 owner 可见的来源连接。只读。 宿主据此渲染来源/连接选择;按数据空间缓存成功结果及在途请求,失败保留原选择。
  • switchConnection:显式切换来源连接:解除目标关联、归档旧会话(保留历史),下一次提交建立新来源会话。 活动回合由后端拒绝;成功后清理本地读模型并自增 contextRevision,让宿主重新解析节点会话。
  • readConversation:读取会话权威快照(消息/回合/事件),用于详情面板。
  • submitTurn:从生成面板提交首轮:确保会话存在、接受回合并异步执行。 相同 requestId(由调用方提供稳定身份)命中既有回合时返回 reused: true,不再推理。
  • queryTurn:按确切 requestId 查询回合与快照(断流/unknown 恢复;不重新 dispatch)。
  • locateTurnByRun:按领域运行关联定位确切回合(活动/历史 Agent 记录 → 确切 request/run) 。 只匹配宿主已显式关联的 runId,绝不按 nodeId 跳到最近会话;只读,不 accept/dispatch。 无关联返回 not-found,调用方据此保留原任务详情(不伪造对话)。
  • retryTextSave:取消在途回合(不撤销已提交领域动作)。
  • linkRun:由宿主领域链在 run/task 接受后显式关联(不从节点 active run 反推)。
  • skillStep:按节点读取 Skill 步骤快照(无步骤时 step=null;轮询/刷新复用同一读入口)。
  • skillSteps:画布内最近 Skill 步骤(活动面板投影;有界)。
  • skillStepDetail:按步骤身份读取快照 + 事件重放(面板打开/断线恢复)。
  • cancelSkillStep:用户停止:只请求取消当前尝试,不伪造已取消。
  • regenerateSkillStep:用户改提示词并重新生成:创建递增 attempt,旧尝试保留可核对历史。

AgentConversationServiceHandle

export type AgentConversationServiceHandle = ReturnType<typeof createAgentConversationService>;

成员说明:

  • invalidateDirectory:配置保存后清除连接/模型目录请求缓存;不改变会话事实或草稿。
  • catalog:读取 adapter 授权/能力/账户目录(真实状态,不自动换模型)。
  • mcpStatus:内置 MCP 真实发现 + 外部连接指引(宿主投影) 。 builtin.ready 只来自后端 executed initialize/源码声明;external 只是当前 origin 的 Streamable HTTP URL,复制地址不等于外部客户端已连接。
  • listConversations:当前画布的会话列表(有界)。
  • findConversationForTarget:按生成目标节点查找该节点当前会话(一个节点复用一条;design D8)。只读。 无则 conversation: null(调用方据此新建);不改变导航或读模型。 connectionId 提供时只返回该来源连接下的会话。
  • clearContext:清空节点上下文:解除该节点与当前会话的关联(归档旧会话,不删除历史;design D8)。 随后该节点提交将新建会话;同时清理本地读模型中该会话的 active/detail。
  • listConnections:该 owner 可见的来源连接。只读。 宿主据此渲染来源/连接选择;按数据空间缓存成功结果及在途请求,失败保留原选择。
  • switchConnection:显式切换来源连接:解除目标关联、归档旧会话(保留历史),下一次提交建立新来源会话。 活动回合由后端拒绝;成功后清理本地读模型并自增 contextRevision,让宿主重新解析节点会话。
  • readConversation:读取会话权威快照(消息/回合/事件),用于详情面板。
  • submitTurn:从生成面板提交首轮:确保会话存在、接受回合并异步执行。 相同 requestId(由调用方提供稳定身份)命中既有回合时返回 reused: true,不再推理。
  • queryTurn:按确切 requestId 查询回合与快照(断流/unknown 恢复;不重新 dispatch)。
  • locateTurnByRun:按领域运行关联定位确切回合(活动/历史 Agent 记录 → 确切 request/run) 。 只匹配宿主已显式关联的 runId,绝不按 nodeId 跳到最近会话;只读,不 accept/dispatch。 无关联返回 not-found,调用方据此保留原任务详情(不伪造对话)。
  • retryTextSave:取消在途回合(不撤销已提交领域动作)。
  • linkRun:由宿主领域链在 run/task 接受后显式关联(不从节点 active run 反推)。
  • skillStep:按节点读取 Skill 步骤快照(无步骤时 step=null;轮询/刷新复用同一读入口)。
  • skillSteps:画布内最近 Skill 步骤(活动面板投影;有界)。
  • skillStepDetail:按步骤身份读取快照 + 事件重放(面板打开/断线恢复)。
  • cancelSkillStep:用户停止:只请求取消当前尝试,不伪造已取消。
  • regenerateSkillStep:用户改提示词并重新生成:创建递增 attempt,旧尝试保留可核对历史。
  • openDetail:详情打开时读取会话快照;只读,不 dispatch。
  • clearDetail:只清除详情读模型缓存,不改变导航 route(design D6a:route 是唯一展开状态源)。 详情面板卸载时调用(含 StrictMode 重放与切到其它 route);导航关闭由 collapseDetail 或 navigation transition 负责,避免卸载清理反过来改写 route。
  • closeDetail:收起详情并恢复合法来源 route(导航语义);用于显式「返回生成面板」。
  • canReturnToSource:当前详情是否仍能「返回生成面板」:来源 route 可用且其节点仍是当前生成目标。 用户已选中别的节点、取消选中或来源节点被删除时返回 false:此时收起详情只是关闭, 不把用户拉回旧节点的生成面板。
  • getDetail:当前详情快照(生成面板与详情共用同一读模型)。
  • navigateToDetail:只读打开详情 route(保存合法来源,不 submit/dispatch)。
  • locateAndOpenDetail:按领域运行关联定位确切回合并只读打开详情 。 用于活动/历史中的 Agent 记录:先按 runId 查宿主 ledger 的确切回合(不按 nodeId 跳到 最近会话),命中再打开详情;未关联返回 not-found,调用方保留原任务详情。
  • collapseDetail:收起详情 route 并恢复合法来源生成面板。

AgentConversationSnapshotView

export type AgentConversationSnapshotView = {
pendingSubmissions?: Readonly<Record<string, AgentEntryIntent>>;
turnsByRequest?: Readonly<Record<string, AgentConversationActiveTurn>>;
conversations: ConversationSummary[];
active: AgentConversationActiveTurn | null;
detail: ConversationSnapshot | null;
mcp: AgentMcpStatusResponse | null;
loading: boolean;
error: string | null;
contextRevision: number;
};

关联类型:AgentEntryIntent · AgentConversationActiveTurn · ConversationSummary · ConversationSnapshot · AgentMcpStatusResponse

成员说明:

  • pendingSubmissions:Local requests awaiting acceptance; never operation records or persisted history.
  • turnsByRequest:Exact request index; active is retained only for legacy consumers.
  • mcp:内置 MCP 真实发现 + 外部连接指引(最近一次查询;未查询为 null)。
  • contextRevision:上下文版本:清空上下文成功后自增,供宿主重新解析节点会话(design D8)。

AgentConversationSubmitInput

生成面板提交首轮时需要的最小目标身份(与 AuthoringGenerationProps 对齐,不复制路由)。

export type AgentConversationSubmitInput = {
canvasId: string;
adapterId?: string;
conversationId?: string;
connectionId?: string;
entry: AgentEntryIntent;
};

关联类型:AgentEntryIntent

成员说明:

  • adapterId:adapter id(缺省由宿主选择首个可用 public adapter)。
  • conversationId:已存在的会话(同一生成目标重复提交时复用,避免每次新会话)。
  • connectionId:选定来源连接。
  • entry:目标动作 intent;discuss 只读。

AgentConversationSubmitResult

提交结果:建立/复用会话并接受一个回合(异步执行由后端 dispatch)。

export type AgentConversationSubmitResult = {
conversationId: string;
requestId: string;
turn: ConversationTurn;
reused: boolean;
};

关联类型:ConversationTurn

成员说明:

  • reused:true 表示相同 requestId+输入命中既有回合,未重复推理。

AgentConversationView

只读订阅视图:生成面板据此展示权威状态与详情入口。

export type AgentConversationView = {
getSnapshot: () => AgentConversationSnapshotView;
subscribe: (listener: () => void) => () => void;
};

关联类型:AgentConversationSnapshotView

AgentDetailAction

export type AgentDetailAction = {
label: string;
summary: string;
emphasis: AgentDetailActionEmphasis;
};

关联类型:AgentDetailActionEmphasis

成员说明:

  • label:具名动作文案(MUST NOT 仅为图标)。
  • summary:与入口同排的摘要(阶段/结果)。
  • emphasis:显著程度:运行与终态为 strong,idle 既往会话为 low。

AgentDetailActionEmphasis

export type AgentDetailActionEmphasis = "low" | "strong";

AgentDetailStatus

生成面板投影的入口状态:权威回合状态加上「尚无回合」的 idle。

export type AgentDetailStatus = ConversationTurnStatus | "idle";

关联类型:ConversationTurnStatus

AgentIcon

Agent 来源与运行时。

export const AgentIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

AlertDialog

export function AlertDialog(props: AlertDialogProps): React.JSX.Element;

关联类型:AlertDialogProps

AlertDialogProps

export type AlertDialogProps = {
instanceId: string;
title: string;
description: string;
confirmLabel?: string;
cancelLabel?: string;
danger?: boolean;
children?: ReactNode;
onCancel: () => void;
onConfirm: () => Promise<AsyncConfirmResult>;
onBusyChange?: (busy: boolean) => void;
};

关联类型:AsyncConfirmResult

成员说明:

  • onCancel:点击取消(含 Escape/遮罩,由 Host 传同一入口)。
  • onConfirm:异步确认。成功(ok: true)时组件不自行关闭,由 Host/调用方按 instanceId 关闭; 失败时保留打开并展示错误。
  • onBusyChange:busy 状态变化回调(Host 用于阻止隐式关闭)。

AlertDialogSurface

AlertDialog 变体:在 Host 内复用 Radix Dialog surface;Escape/outside 仍只作为 close request 交给 Host policy(busy/dismissible 判定保留在 Host)。

export function AlertDialogSurface(props: DialogSurfaceProps): React.JSX.Element;

关联类型:DialogSurfaceProps

AlignBottomIcon

export const AlignBottomIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps