@vtj/designer 0.18.27 → 0.19.0

package/types/components/widgets/agent/composables/useFileRecognition.d.ts

@@ -0,0 +1,46 @@
+import { AttachmentInfo } from '../types/agent';
+import { Ref, ComputedRef } from 'vue';
+export interface UploadedFile {
+    id: string;
+    name: string;
+    type: 'image' | 'json';
+    description: string;
+    recognizing: boolean;
+    error: string;
+    /** 图片的 objectURL，用于缩略图预览 */
+    previewUrl: string;
+    /** 识别成功后后端返回的文件访问地址 */
+    url: string;
+}
+export declare function useFileRecognition(recognitionFile: (file: File) => Promise<{
+    title?: string;
+    content?: string;
+    type?: string;
+    url?: string;
+}>): {
+    files: Ref<{
+        id: string;
+        name: string;
+        type: "image" | "json";
+        description: string;
+        recognizing: boolean;
+        error: string;
+        previewUrl: string;
+        url: string;
+    }[], UploadedFile[] | {
+        id: string;
+        name: string;
+        type: "image" | "json";
+        description: string;
+        recognizing: boolean;
+        error: string;
+        previewUrl: string;
+        url: string;
+    }[]>;
+    recognizing: ComputedRef<boolean>;
+    uploadFile: (file: File) => Promise<void>;
+    removeFile: (fileId: string) => void;
+    buildFilePrompt: () => string;
+    buildAttachments: () => AttachmentInfo[];
+    clearFiles: () => void;
+};

package/types/components/widgets/agent/composables/useReplayChat.d.ts

@@ -0,0 +1,5 @@
+import { Ref } from 'vue';
+import { ConversationRound, ReplayChatDeps } from '../types/agent';
+export declare function useReplayChat(deps: ReplayChatDeps, conversationRounds: Ref<ConversationRound[]>): {
+    loadChatHistory: (topicId: string) => Promise<void>;
+};

package/types/components/widgets/agent/composables/useSSEStream.d.ts

@@ -0,0 +1,7 @@
+import { SSEChunkData, StreamCompletionResult } from '../types/agent';
+type ChatCompletions = (topicId: string, chatId: string, callback?: (data: SSEChunkData | null, done?: boolean) => void, error?: (error: Error, cancel?: boolean) => void) => Promise<(() => void) | undefined>;
+export declare function useSSEStream(chatCompletions: ChatCompletions): {
+    streamCompletion: (topicId: string, chatId: string, onChunk?: (text: string) => void, onReasoning?: (text: string) => void) => Promise<StreamCompletionResult>;
+    abortAll: () => void;
+};
+export {};

package/types/components/widgets/agent/constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Agent 模块常量
+ * 集中管理流程参数、超时、存储键等可配置项
+ */
+/** Editor 单步骤内最大工具调用轮次（ReAct 循环上限） */
+export declare const MAX_TURNS = 10;
+/** 工具执行超时时间（毫秒） */
+export declare const TOOL_TIMEOUT_MS = 30000;
+/** 代码块显示偏好存储键 */
+export declare const HIDE_CODE_STORAGE_KEY = "CHAT_HIDE_CODE";
+/** 滚动判断"接近底部"的阈值（像素） */
+export declare const SCROLL_NEAR_BOTTOM_THRESHOLD = 80;
+/** 服务端"额度/Token 用尽"错误文案片段（命中时弹出付费提示） */
+export declare const PAY_LIMIT_MESSAGES: string[];
+/** 判断错误文案是否命中付费提示条件 */
+export declare const isPayLimitError: (text: string) => boolean;

package/types/components/widgets/agent/conversation-round.d.ts

@@ -0,0 +1,26 @@
+import { ConversationRound } from './types/agent';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    round: ConversationRound;
+    roundNumber: number;
+    isLatest: boolean;
+    retryable: boolean;
+    code: boolean;
+    detailsCommand: number;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    view: (source: string, language: string, dsl?: Record<string, any> | undefined) => any;
+    resolveApproval: (id: string, approved: boolean) => any;
+    apply: (dsl: Record<string, any>) => any;
+    retryStep: (stepIndex: number) => any;
+    retrySummary: () => any;
+    retryArchitect: () => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onView?: ((source: string, language: string, dsl?: Record<string, any> | undefined) => any) | undefined;
+    onResolveApproval?: ((id: string, approved: boolean) => any) | undefined;
+    onApply?: ((dsl: Record<string, any>) => any) | undefined;
+    onRetryStep?: ((stepIndex: number) => any) | undefined;
+    onRetrySummary?: (() => any) | undefined;
+    onRetryArchitect?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLElement>;
+export default _default;

package/types/components/widgets/{ai → agent}/detail.d.ts

@@ -1,14 +1,15 @@
-import { AIChat } from '../../hooks';
 import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions, CreateComponentPublicInstanceWithMixins, GlobalComponents, GlobalDirectives } from 'vue';
 import { Props } from '../../editor/Editor';
-export interface Props {
-    chat: AIChat;
-    updateChatDsl: any;
-}
-declare const _default: DefineComponent<Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-    apply: (chat: AIChat, manual?: boolean | undefined) => any;
-}, string, PublicProps, Readonly<Props> & Readonly<{
-    onApply?: ((chat: AIChat, manual?: boolean | undefined) => any) | undefined;
+type __VLS_Props = {
+    source: string;
+    language: string;
+    dsl: any;
+    updateDsl: (source: string) => Promise<any>;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    apply: (dsl: any) => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onApply?: ((dsl: any) => any) | undefined;
 }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
     editorRef: CreateComponentPublicInstanceWithMixins<Readonly< Props> & Readonly<{
         "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;

package/types/components/widgets/agent/editor-step.d.ts

@@ -0,0 +1,22 @@
+import { EditorStepResult } from './types/agent';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    step: EditorStepResult;
+    code: boolean;
+    detailsCommand: number;
+    retryable: boolean;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    view: (source: string, language: string, dsl?: Record<string, any> | undefined) => any;
+    retry: () => any;
+    resolveApproval: (id: string, approved: boolean) => any;
+    apply: (dsl: Record<string, any>) => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onView?: ((source: string, language: string, dsl?: Record<string, any> | undefined) => any) | undefined;
+    onRetry?: (() => any) | undefined;
+    onResolveApproval?: ((id: string, approved: boolean) => any) | undefined;
+    onApply?: ((dsl: Record<string, any>) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+    turnContentRefs: HTMLDivElement;
+}, HTMLElement>;
+export default _default;

package/types/components/widgets/agent/index.d.ts

@@ -0,0 +1,21 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions, CreateComponentPublicInstanceWithMixins, GlobalComponents, GlobalDirectives } from 'vue';
+import { Props } from './pay-tip';
+declare const _default: DefineComponent<{}, {
+    newTask: () => void;
+    start: () => Promise<void>;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {
+    payTipRef: CreateComponentPublicInstanceWithMixins<Readonly< Props> & Readonly<{}>, {
+        show: () => void;
+    }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, PublicProps, {}, false, {}, {}, GlobalComponents, GlobalDirectives, string, {}, any, ComponentProvideOptions, {
+        P: {};
+        B: {};
+        D: {};
+        C: {};
+        M: {};
+        Defaults: {};
+    }, Readonly< Props> & Readonly<{}>, {
+        show: () => void;
+    }, {}, {}, {}, {}> | null;
+    conversationRef: HTMLDivElement;
+}, any>;
+export default _default;

package/types/components/widgets/{ai → agent}/invite-tip.d.ts

@@ -1,4 +1,4 @@
-import { Settings } from '../../hooks';
+import { Settings } from '../../../framework';
 import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
 export interface Props {
     settings?: Settings;

package/types/components/widgets/agent/message-input.d.ts

@@ -0,0 +1,35 @@
+import { DictOption } from '../../../framework';
+import { UploadedFile } from './composables/useFileRecognition';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    message: string;
+    running: boolean;
+    hasTopic: boolean;
+    files: UploadedFile[];
+    recognizing: boolean;
+    autoApprove: boolean;
+    model: string;
+    models: DictOption[];
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    abort: () => any;
+    "update:message": (value: string) => any;
+    start: () => any;
+    continue: () => any;
+    "update:autoApprove": (value: boolean) => any;
+    "update:model": (value: string) => any;
+    "upload-file": (file: File) => any;
+    "remove-file": (fileId: string) => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onAbort?: (() => any) | undefined;
+    "onUpdate:message"?: ((value: string) => any) | undefined;
+    onStart?: (() => any) | undefined;
+    onContinue?: (() => any) | undefined;
+    "onUpdate:autoApprove"?: ((value: boolean) => any) | undefined;
+    "onUpdate:model"?: ((value: string) => any) | undefined;
+    "onUpload-file"?: ((file: File) => any) | undefined;
+    "onRemove-file"?: ((fileId: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+    fileInputRef: HTMLInputElement;
+}, HTMLElement>;
+export default _default;

package/types/components/widgets/{ai → agent}/pay-tip.d.ts

@@ -1,4 +1,4 @@
-import { Settings } from '../../hooks';
+import { Settings } from '../../../framework';
 import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
 export interface Props {
     settings?: Settings;
@@ -8,5 +8,7 @@ export interface Props {
     getOrder: any;
     getImage: (path?: string) => string | undefined;
 }
-declare const _default: DefineComponent<Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+declare const _default: DefineComponent<Props, {
+    show: () => void;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 export default _default;

package/types/components/widgets/agent/records.d.ts

@@ -0,0 +1,18 @@
+import { AITopic } from '../../../framework';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    topics?: AITopic[];
+    current?: AITopic | null;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    load: (topic: AITopic) => any;
+    remove: (topic: AITopic) => any;
+    new: () => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onLoad?: ((topic: AITopic) => any) | undefined;
+    onRemove?: ((topic: AITopic) => any) | undefined;
+    onNew?: (() => any) | undefined;
+}>, {
+    topics: AITopic[];
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/types/components/widgets/{ai → agent}/stream-markdown.d.ts

@@ -4,9 +4,9 @@ type __VLS_Props = {
     code?: boolean;
 };
 declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-    click: (...args: any[]) => void;
+    click: (source: string, language: string) => any;
 }, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onClick?: ((...args: any[]) => any) | undefined;
+    onClick?: ((source: string, language: string) => any) | undefined;
 }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
     container: HTMLDivElement;
 }, HTMLDivElement>;

package/types/components/widgets/agent/summary.d.ts

@@ -0,0 +1,19 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+type __VLS_Props = {
+    text: string;
+    reasoning: string;
+    error: string;
+    code: boolean;
+    detailsCommand: number;
+    retryable: boolean;
+};
+declare const _default: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    view: (source: string, language: string) => any;
+    retry: () => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onView?: ((source: string, language: string) => any) | undefined;
+    onRetry?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+    reasoningPreRef: HTMLPreElement;
+}, any>;
+export default _default;

package/types/components/widgets/agent/types/agent.d.ts

@@ -0,0 +1,346 @@
+import { Ref } from 'vue';
+import { Engine, TopicDto, ChatDto } from '../../../../framework';
+import { Access } from '@vtj/renderer';
+import { AgentStatusMessage } from '../utils/messages';
+/** SSE 数据块（与框架 CompletionChunk 结构兼容，含服务端扩展的 vtj 字段） */
+export interface SSEChunkData {
+    id?: string;
+    model?: string;
+    choices?: Array<{
+        delta?: {
+            content?: string | null;
+            reasoning_content?: string | null;
+        };
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    } | null;
+    vtj?: {
+        model?: string;
+        agent?: string;
+    };
+}
+/** SSE 流完成结果 */
+export interface StreamCompletionResult {
+    done: () => void;
+    reasoning: string;
+    usage: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    } | null;
+    modelUsed: string;
+    /** reasoning 阶段持续时间（毫秒） */
+    reasoningTime: number;
+}
+/** 计划步骤 */
+export interface PlanStep {
+    id: string;
+    type: 'tool_call' | 'vue_code' | 'diff' | 'text';
+    description: string;
+    target?: string;
+    toolName?: string;
+    /** 步骤依赖（服务端 HarnessPlan 协议字段，透传保留） */
+    dependsOn?: string[];
+}
+/** Architect 返回的计划 */
+export interface PlanResult {
+    intent: string;
+    safety: 'readonly' | 'write' | 'destructive';
+    steps: PlanStep[];
+    answer?: string;
+    /** 计划上下文键（服务端 HarnessPlan 协议字段，透传保留） */
+    contextKeys?: string[];
+}
+/** Editor 每轮对话信息 */
+export interface EditorTurn {
+    turn: number;
+    type: string;
+    content: string;
+    reasoning: string;
+    /** Vue/Diff 执行后的最终源码与 DSL */
+    vue?: string;
+    dsl?: Record<string, any>;
+    prompt?: string;
+    toolAction?: string;
+    toolParams?: unknown[];
+    toolResult?: {
+        success: boolean;
+        result?: unknown;
+        error?: string;
+        duration: number;
+    };
+    resultSummary?: string;
+    approval?: {
+        id: string;
+        action: string;
+        risk: 'write' | 'destructive';
+        status: 'pending' | 'approved' | 'rejected';
+    };
+}
+/** Editor 步骤执行结果（UI 展示用） */
+export interface EditorStepResult {
+    stepIdx: number;
+    step: PlanStep;
+    content: string;
+    reasoning: string;
+    error: string | null;
+    done: boolean;
+    turns: EditorTurn[];
+    tokens?: number;
+    duration?: number;
+    /** 取消时产生的未完成槽位标记（断点恢复时定位用） */
+    aborted?: boolean;
+}
+/** 步骤执行返回值（内部使用） */
+export interface StepExecutionResult {
+    content: string;
+    error: string | null;
+    tokens: number;
+    duration: number;
+    toolResult?: {
+        action: string;
+        result: unknown;
+    } | null;
+}
+/** 步骤记录（用于总结和 trace） */
+export interface StepRecord {
+    stepId: string;
+    type: string;
+    description: string;
+    status: 'completed' | 'failed';
+    content: string;
+    error: string | null;
+    tokens: number;
+    duration: number;
+}
+/** 附件展示信息（不含识别描述，描述仅用于提交请求） */
+export interface AttachmentInfo {
+    id: string;
+    name: string;
+    type: 'image' | 'json';
+    /** 文件访问 URL（本地相对路径或 OSS 完整地址） */
+    url?: string;
+}
+/** 一轮完整的 Architect → Editor → Summary 对话 */
+export interface ConversationRound {
+    id: string;
+    userMessage: string;
+    /** Architect 对应的 chats 表记录 ID，重试时复用避免重复插入 */
+    architectChatId: string;
+    architectPlan: PlanResult | null;
+    architectAnswer: string;
+    architectStreamText: string;
+    reasoningText: string;
+    /** Architect 规划失败原因（大模型输出无效/异常时记录，UI 与导出展示） */
+    architectError?: string;
+    /** Architect 规划自动重试次数（大模型输出无效时自动重发） */
+    architectRetryCount?: number;
+    editorResults: EditorStepResult[];
+    summaryText: string;
+    summaryReasoning: string;
+    summaryError: string;
+    summaryAttempt: number;
+    /** 附件快照（气泡展示用，与输入框 files 解耦） */
+    attachments?: AttachmentInfo[];
+    /** 实际提交后端的完整 prompt（含文件识别描述），重试时复用 */
+    promptSent?: string;
+}
+/** 导出数据结构 */
+export interface ExportData {
+    exportTime: string;
+    topicId: string;
+    model: string;
+    userMessage: string;
+    /** 所有对话轮次 */
+    rounds?: ExportRound[];
+}
+/** 导出单轮数据 */
+export interface ExportRound {
+    userMessage: string;
+    architect?: {
+        reasoning: string | null;
+        output: string | null;
+        plan: PlanResult | null;
+        answer: string | null;
+    };
+    steps: ExportedStep[];
+    summary?: string;
+    /** 总结生成错误信息 */
+    summaryError?: string;
+    /** Architect 规划失败原因 */
+    architectError?: string;
+    /** 本轮错误信息 */
+    error?: string;
+}
+/** 导出的步骤数据 */
+export interface ExportedStep {
+    index: number;
+    stepId: string;
+    description: string;
+    type: string;
+    status: 'failed' | 'completed' | 'executing';
+    error: string | null;
+    turns: ExportedTurn[];
+}
+/** 导出的轮次数据 */
+export interface ExportedTurn {
+    turn: number;
+    type: string;
+    prompt: string | null;
+    output: string;
+    reasoning?: string;
+    toolCall?: {
+        action: string;
+        parameters: unknown[] | null;
+        result?: {
+            success: boolean;
+            result: unknown;
+            error: unknown;
+            duration: number;
+        };
+    };
+    resultSummary?: string;
+}
+/** 创建话题请求体（扩展自框架 TopicDto） */
+export interface AgentTopicBody extends TopicDto {
+    agent?: 'architect' | 'editor';
+    userId?: string;
+    userName?: string;
+    files?: string;
+    requestId?: string;
+}
+/** 创建聊天请求体（扩展自框架 ChatDto） */
+export interface AgentChatBody extends ChatDto {
+    agent?: 'architect' | 'editor';
+    stepId?: string;
+    attempt?: number;
+    userId?: string;
+    userName?: string;
+    files?: string;
+    requestId?: string;
+}
+/** 保存聊天记录请求体（chats 表字段） */
+export interface SaveChatBody {
+    id: string;
+    topicId: string;
+    userId: string;
+    status?: string;
+    content?: string;
+    reasoning?: string;
+    modelUsed?: string;
+    tokens?: number;
+    tokensPrompt?: number;
+    tokensCompletion?: number;
+    thinking?: number;
+    toolCallId?: string;
+    toolContent?: string;
+    vue?: string;
+    dsl?: string;
+    source?: string;
+}
+/** 更新话题请求体 */
+export interface UpdateTopicBody {
+    id: string;
+    status?: string;
+    planJson?: PlanResult | null;
+    traceId?: string;
+    currentStepId?: string;
+}
+/** 保存 trace 请求体 */
+export interface SaveTraceBody {
+    traceId: string;
+    topicId: string;
+    planJson: PlanResult | null;
+    stepsJson: StepRecord[];
+    finalStatus: 'failed' | 'completed';
+    totalTokens: number;
+    totalDuration: number;
+}
+/** 基础设施依赖 */
+export interface DualAgentInfrastructure {
+    token: Ref<string>;
+    model: Ref<string>;
+    existingTopicId: Ref<string>;
+    setTopicId: (id: string) => void;
+    getEngine: () => Engine | null;
+    registerTools: () => void;
+    abortSse: () => void;
+    access?: Access;
+    setStatus: (message: AgentStatusMessage) => void;
+}
+/** API 依赖 */
+export interface DualAgentApi {
+    postTopic: (body: AgentTopicBody) => Promise<any>;
+    postChat: (body: AgentChatBody) => Promise<any>;
+    executeArchitectPlan: (topicId: string, architectChatId: string, userId: string, traceId: string, userMessage: string, round: ConversationRound, signal?: AbortSignal) => Promise<void>;
+    retryEditorPlan: (topicId: string, userId: string, traceId: string, userMessage: string, round: ConversationRound, stepIndex: number, signal?: AbortSignal) => Promise<void>;
+    resumeEditorPlan: (topicId: string, userId: string, traceId: string, userMessage: string, round: ConversationRound, signal?: AbortSignal) => Promise<void>;
+    retrySummary: (topicId: string, userId: string, traceId: string, userMessage: string, round: ConversationRound, signal?: AbortSignal) => Promise<void>;
+}
+/** 对话状态 */
+export interface DualAgentState {
+    conversationRounds: Ref<ConversationRound[]>;
+}
+/** Editor 步骤执行依赖 */
+export interface EditorStepDeps {
+    streamCompletion: (topicId: string, chatId: string, onChunk?: (text: string) => void, onReasoning?: (text: string) => void) => Promise<StreamCompletionResult>;
+    postChat: (body: AgentChatBody) => Promise<any>;
+    saveChat: (body: SaveChatBody) => Promise<any>;
+    updateTopic: (body: UpdateTopicBody) => Promise<any>;
+    getEngine: () => Engine | null;
+    setStatus: (message: AgentStatusMessage) => void;
+    requestApproval: (id: string) => Promise<boolean>;
+}
+/** Architect 规划执行依赖 */
+export interface ArchitectPlanDeps {
+    streamCompletion: (topicId: string, chatId: string, onChunk?: (text: string) => void, onReasoning?: (text: string) => void) => Promise<StreamCompletionResult>;
+    postChat: (body: AgentChatBody) => Promise<any>;
+    saveChat: (body: SaveChatBody) => Promise<any>;
+    updateTopic: (body: UpdateTopicBody) => Promise<any>;
+    saveTrace: (body: SaveTraceBody) => Promise<any>;
+    setStatus: (message: AgentStatusMessage) => void;
+    executeEditorStep: (topicId: string, userId: string, step: PlanStep, stepIdx: number, allSteps: PlanStep[], stepStart: number, editorResults: EditorStepResult[], signal?: AbortSignal, retrySlot?: EditorStepResult) => Promise<StepExecutionResult>;
+}
+/** 后端返回的 chat 记录（transformChat 后格式） */
+export interface ChatRecord {
+    id: string;
+    topicId: string;
+    userId: string;
+    userName: string;
+    /** 用户提示词 (原 userContent) */
+    prompt: string;
+    /** AI 回复内容 (原 assistantContent) */
+    content: string;
+    /** 推理内容 (原 reasoningContent) */
+    reasoning: string;
+    status: string;
+    /** token 用量 (原 tokenUsage) */
+    tokens: number;
+    /** 错误消息 (原 errorMessage) */
+    message: string;
+    /** 思考用时毫秒 (原 thinkingTime) */
+    thinking: number;
+    modelUsed: string;
+    agentRole: string;
+    stepId: string;
+    attempt: number;
+    tokensPrompt: number;
+    tokensCompletion: number;
+    toolCallId: string;
+    toolContent: string;
+    vue: string;
+    source: string;
+    dsl: Record<string, any> | string;
+    /** 附件信息（持久化到 chats.files） */
+    files?: AttachmentInfo[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** 回显 composable 依赖 */
+export interface ReplayChatDeps {
+    getChats: (topicId: string) => Promise<ChatRecord[]>;
+    setStatus: (message: AgentStatusMessage) => void;
+}

package/types/components/widgets/agent/utils/approval.d.ts

@@ -0,0 +1,10 @@
+import { EditorTurn } from '../types/agent';
+export type ApprovalRisk = 'write' | 'destructive';
+export declare function createEditorTurn(turn: number): EditorTurn;
+/**
+ * 获取工具调用的审批风险等级
+ * @param action 工具名称
+ * @param declared 工具定义中显式声明的风险等级（优先使用）
+ * @returns 需要审批时返回风险等级，无需审批（只读操作）返回 null
+ */
+export declare function getApprovalRisk(action: string, declared?: ApprovalRisk | null): ApprovalRisk | null;

package/types/components/widgets/agent/utils/breakpoint.d.ts

@@ -0,0 +1,2 @@
+import { ConversationRound } from '../types/agent';
+export declare function hasResumableBreakpoint(rounds: ConversationRound[]): boolean;

package/types/components/widgets/agent/utils/chat.d.ts

@@ -0,0 +1,10 @@
+import { SaveChatBody, StreamCompletionResult } from '../types/agent';
+export declare function buildChatSaveBody(opts: {
+    id: string;
+    topicId: string;
+    userId: string;
+    status?: string;
+    content?: string;
+    result: StreamCompletionResult | null;
+    tokens?: number;
+}): SaveChatBody;

package/types/components/widgets/agent/utils/export.d.ts

@@ -0,0 +1,4 @@
+import { ConversationRound } from '../types/agent';
+/** 从轮次数据推导错误信息 */
+export declare function deriveError(r: ConversationRound): string | undefined;
+export declare function exportConversation(existingTopicId: string, model: string, rounds: ConversationRound[]): void;