@gt-fe/eap-runtime 0.0.8

package/dist/graph/nodes/llm-node.js

@@ -0,0 +1,281 @@
+/**
+ * LLM Node — LLM 执行节点
+ *
+ * 代表 Graph 中的 LLM 推理节点，支持：
+ * - 流式输出（逐 token 推送）
+ * - Token 计数（inputTokens/outputTokens）
+ * - 重试 + 指数退避（默认 3 次）
+ *
+ * @see design.md §1.2 LLM 节点执行流程
+ * @see requirements.md Requirement 1 AC6, Requirement 9
+ */
+import { formatUnknownError } from '../../utils/format-error.js';
+// ─────────────────────────────────────────────
+// Default retry config
+// ─────────────────────────────────────────────
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    backoff: {
+        type: 'exponential',
+        baseDelay: 1000,
+        maxDelay: 30000,
+        jitter: 0.1,
+    },
+};
+// ─────────────────────────────────────────────
+// LLMNode
+// ─────────────────────────────────────────────
+/**
+ * LLMNode — LLM 执行节点
+ *
+ * 在 StateGraph 中作为 node function 注册，负责：
+ * 1. 从 state 中提取 messages
+ * 2. 调用 ILLMProvider 执行推理（支持 invoke / stream 模式）
+ * 3. 统计 Token 消耗
+ * 4. 失败时按 NodeRetryConfig 重试
+ * 5. 将 LLM 响应追加到 state.messages 并返回
+ */
+export class LLMNode {
+    config;
+    provider;
+    retryConfig;
+    nodeId;
+    streaming;
+    onChunk;
+    /**
+     * @param nodeId - 节点唯一标识
+     * @param config - LLM 节点配置
+     * @param provider - LLM 调用提供者
+     * @param streaming - 是否启用流式输出（默认 false）
+     * @param onChunk - 流式模式下每个文本片段回调（用于 SSE response.chunk）
+     */
+    constructor(nodeId, config, provider, streaming = false, onChunk) {
+        this.nodeId = nodeId;
+        this.config = config;
+        this.provider = provider;
+        this.streaming = streaming;
+        this.onChunk = onChunk;
+        this.retryConfig = {
+            maxRetries: config.retry?.maxRetries ?? DEFAULT_RETRY_CONFIG.maxRetries,
+            backoff: config.retry?.backoff ?? DEFAULT_RETRY_CONFIG.backoff,
+        };
+    }
+    /**
+     * execute — StateGraph 节点函数
+     *
+     * 从 state 提取 messages → 调用 LLM → 处理重试 → 返回更新后的 state
+     */
+    async execute(state) {
+        const messages = this.extractMessages(state);
+        // 注入 system prompt
+        const messagesWithSystem = this.prependSystemPrompt(messages);
+        const startedAt = Date.now();
+        // 带重试的 LLM 调用
+        const response = await this.invokeWithRetry(messagesWithSystem);
+        const durationMs = Date.now() - startedAt;
+        // 构建 assistant message（保留 reasoningContent 供后续 HTTP 回传）
+        const assistantMessage = {
+            role: 'assistant',
+            content: response.content,
+            toolCalls: response.toolCalls?.map((tc) => ({
+                id: tc.id,
+                name: tc.name,
+                arguments: tc.arguments,
+            })),
+            ...(response.reasoningContent
+                ? { reasoningContent: response.reasoningContent }
+                : {}),
+        };
+        // 返回更新后的 state
+        //
+        // 重要：messages channel 的 reducer 是 **append 语义**（[...current, ...update]），
+        // 节点只需返回 **新增消息数组**，reducer 会自动追加到 current。
+        // 如果这里返回 [...currentMessages, newMsg]，会导致 messages 被追加两次
+        // （即 user 消息重复的根因）。
+        //
+        // __llmTokenUsage channel 同样是 **数组累加器 reducer**，每次追加一条使用明细。
+        return {
+            messages: [assistantMessage],
+            currentNode: this.nodeId,
+            __llmTokenUsage: [
+                {
+                    nodeId: this.nodeId,
+                    model: response.model,
+                    inputTokens: response.inputTokens,
+                    outputTokens: response.outputTokens,
+                    durationMs,
+                },
+            ],
+        };
+    }
+    /**
+     * 获取节点 ID
+     */
+    getNodeId() {
+        return this.nodeId;
+    }
+    /**
+     * 获取节点配置
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─────────────────────────────────────────────
+    // Private methods
+    // ─────────────────────────────────────────────
+    /**
+     * 从 state 中提取 messages 并转换为 GraphMessage[]
+     */
+    extractMessages(state) {
+        const raw = state['messages'];
+        if (!Array.isArray(raw)) {
+            return [];
+        }
+        return raw.map((msg) => {
+            if (typeof msg === 'object' && msg !== null) {
+                const m = msg;
+                const toolCalls = (m['toolCalls'] ?? m['tool_calls']);
+                return {
+                    role: m['role'] ?? 'user',
+                    content: m['content'] ?? '',
+                    toolCalls,
+                    toolCallId: typeof m['toolCallId'] === 'string'
+                        ? m['toolCallId']
+                        : typeof m['tool_call_id'] === 'string'
+                            ? m['tool_call_id']
+                            : undefined,
+                    toolName: typeof m['toolName'] === 'string' ? m['toolName'] : undefined,
+                    success: typeof m['success'] === 'boolean' ? m['success'] : undefined,
+                    reasoningContent: typeof m['reasoningContent'] === 'string'
+                        ? m['reasoningContent']
+                        : typeof m['reasoning_content'] === 'string'
+                            ? m['reasoning_content']
+                            : undefined,
+                };
+            }
+            return { role: 'user', content: String(msg) };
+        });
+    }
+    /**
+     * 在 messages 前追加 system prompt（兑底注入）
+     *
+     * 设计说明：
+     * - 当 config.systemPrompt 已设置时，HttpLLMProvider.buildRequestBody 已基于
+     *   config.systemPrompt 注入过 system message，此处**不再重复添加**，避免 messages
+     *   里出现两条相同的 system。
+     * - 仅当 config.systemPrompt 未设置、且 messages 首条不是 system 时，才兑底加一条
+     *   空 system 占位（某些上游调用可能不通过 HttpLLMProvider，保留此兑底安全）。
+     */
+    prependSystemPrompt(messages) {
+        // config.systemPrompt 已设：由 provider 统一注入，此处跳过（消除重复）
+        if (this.config.systemPrompt) {
+            return messages;
+        }
+        // config 未设 + 首条已是 system：保持原样
+        if (messages.length > 0 && messages[0].role === 'system') {
+            return messages;
+        }
+        // config 未设 + 首条非 system：无 system 可加，保持原样
+        return messages;
+    }
+    /**
+     * 带重试逻辑的 LLM 调用
+     *
+     * 根据 streaming 配置选择 invoke 或 stream 模式。
+     * 失败时按 backoff 策略重试，最多重试 maxRetries 次。
+     */
+    async invokeWithRetry(messages) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+            try {
+                if (this.streaming) {
+                    return await this.invokeStreaming(messages);
+                }
+                return await this.provider.invoke(messages, this.config);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(formatUnknownError(error));
+                // 最后一次尝试不需要等待
+                if (attempt < this.retryConfig.maxRetries) {
+                    const delay = this.calculateBackoffDelay(attempt);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        throw new Error(`LLMNode "${this.nodeId}" failed after ${this.retryConfig.maxRetries + 1} attempts: ${lastError ? formatUnknownError(lastError) : 'unknown error'}`);
+    }
+    /**
+     * 流式调用 LLM 并聚合为完整 LLMResponse
+     */
+    async invokeStreaming(messages) {
+        const chunks = [];
+        const reasoningParts = [];
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let toolCalls;
+        const iterator = this.provider.stream(messages, this.config);
+        for await (const chunk of iterator) {
+            if (chunk.content && this.onChunk) {
+                this.onChunk(chunk.content);
+            }
+            chunks.push(chunk.content);
+            if (chunk.reasoningContent) {
+                reasoningParts.push(chunk.reasoningContent);
+            }
+            // 勿用「!== undefined」接受 0：finish 包常先带 0，usage 包后到
+            if (typeof chunk.inputTokens === 'number' && chunk.inputTokens > 0) {
+                inputTokens = chunk.inputTokens;
+            }
+            if (typeof chunk.outputTokens === 'number' && chunk.outputTokens > 0) {
+                outputTokens = chunk.outputTokens;
+            }
+            if (chunk.toolCalls?.length) {
+                toolCalls = chunk.toolCalls;
+            }
+        }
+        const reasoningContent = reasoningParts.join('');
+        return {
+            content: chunks.join(''),
+            toolCalls,
+            ...(reasoningContent ? { reasoningContent } : {}),
+            inputTokens,
+            outputTokens,
+            model: this.config.model,
+        };
+    }
+    /**
+     * 计算退避延迟（支持 exponential / linear / fixed）
+     */
+    calculateBackoffDelay(attempt) {
+        const backoff = this.retryConfig.backoff;
+        let delay;
+        switch (backoff.type) {
+            case 'exponential':
+                delay = backoff.baseDelay * Math.pow(2, attempt);
+                break;
+            case 'linear':
+                delay = backoff.baseDelay * (attempt + 1);
+                break;
+            case 'fixed':
+                delay = backoff.baseDelay;
+                break;
+            default:
+                delay = backoff.baseDelay;
+        }
+        // 应用最大延迟限制
+        delay = Math.min(delay, backoff.maxDelay);
+        // 应用 jitter（如果配置了抖动因子）
+        if (backoff.jitter && backoff.jitter > 0) {
+            const jitterRange = delay * backoff.jitter;
+            delay += Math.random() * jitterRange * 2 - jitterRange;
+            delay = Math.max(0, delay);
+        }
+        return Math.round(delay);
+    }
+    /**
+     * 延迟等待
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/graph/nodes/skill-bind-node.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 可选图胶水：把 silent LLM 的结构化输出写成 activeSkillPrompt / skillRoute。
+ * 不是 Graph 节点类型。任何「多本手册互斥」的域图都可选用；字段是约定不是契约。
+ */
+import type { LoadedSkillInfo, LoadedSkillMap } from '../../tool/system-prompt-builder.js';
+export type SkillRoute = 'skill' | 'clarify' | 'none';
+export interface SkillBindPatch {
+    skillRoute: SkillRoute;
+    activatedSkill: string | null;
+    /** 展示名；未选中时为空 */
+    skillName?: string;
+    activeSkillPrompt?: string;
+    skillInput?: Record<string, unknown>;
+    messages: Array<Record<string, unknown>>;
+    /** 用户写了 skill 名但清单里没有，才算 unmatched */
+    unmatched?: boolean;
+}
+interface SkillSelectPayload {
+    activatedSkill?: unknown;
+    needsClarification?: unknown;
+    clarificationQuestion?: unknown;
+    params?: unknown;
+    confidence?: unknown;
+}
+export declare function extractJsonObject(text: string): SkillSelectPayload | null;
+export declare function resolveSkillDefinition(defs: LoadedSkillMap | undefined, rawName: string): LoadedSkillInfo | undefined;
+/**
+ * 消费选择节点刚写出的 assistant JSON，改写为路由 + Skill 提示词。
+ * 返回的 messages 是**整段替换**（调用方须覆盖 messages channel 时改用 replace 语义）。
+ */
+export declare function bindSelectedSkill(state: Record<string, unknown>): SkillBindPatch;
+export {};

package/dist/graph/nodes/skill-bind-node.js

@@ -0,0 +1,116 @@
+function lastAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (!msg || msg.role !== 'assistant')
+            continue;
+        return typeof msg.content === 'string' ? msg.content : '';
+    }
+    return '';
+}
+export function extractJsonObject(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidate = fenced?.[1]?.trim() ?? trimmed;
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const parsed = JSON.parse(candidate.slice(start, end + 1));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveSkillDefinition(defs, rawName) {
+    if (!defs || !rawName || rawName === 'none')
+        return undefined;
+    if (defs[rawName])
+        return defs[rawName];
+    const needle = rawName.trim().toLowerCase();
+    return Object.values(defs).find((skill) => {
+        return (skill.skillId.toLowerCase() === needle ||
+            (skill.name && skill.name.toLowerCase() === needle));
+    });
+}
+function formatParams(params) {
+    return Object.entries(params)
+        .map(([key, value]) => `- ${key}: ${JSON.stringify(value)}`)
+        .join('\n');
+}
+function buildSkillPrompt(skill, params) {
+    const parts = [`# 技能：${skill.name || skill.skillId}`];
+    if (skill.description) {
+        parts.push(skill.description);
+    }
+    if (params && Object.keys(params).length > 0) {
+        parts.push(`# 提取的参数\n${formatParams(params)}`);
+    }
+    if (skill.prompt?.trim()) {
+        parts.push(skill.prompt.trim());
+    }
+    return parts.join('\n\n');
+}
+/**
+ * 消费选择节点刚写出的 assistant JSON，改写为路由 + Skill 提示词。
+ * 返回的 messages 是**整段替换**（调用方须覆盖 messages channel 时改用 replace 语义）。
+ */
+export function bindSelectedSkill(state) {
+    const incoming = Array.isArray(state.messages) ? [...state.messages] : [];
+    const fromState = (typeof state.silentOutput === 'string' && state.silentOutput)
+        || (typeof state.skillSelectRaw === 'string' ? state.skillSelectRaw : '');
+    const lastText = lastAssistantText(incoming);
+    const lastIsSelector = extractJsonObject(lastText) !== null;
+    const parsed = extractJsonObject(fromState) ?? extractJsonObject(lastText);
+    const defs = state.skillDefinitions;
+    const nextMessages = () => {
+        const next = incoming.filter((item) => Boolean(item) && typeof item === 'object');
+        if (!lastIsSelector)
+            return next;
+        for (let i = next.length - 1; i >= 0; i--) {
+            if (next[i]?.role === 'assistant') {
+                next.splice(i, 1);
+                break;
+            }
+        }
+        return next;
+    };
+    if (!parsed) {
+        return { skillRoute: 'none', activatedSkill: null, messages: nextMessages() };
+    }
+    const needsClarification = parsed.needsClarification === true;
+    const question = typeof parsed.clarificationQuestion === 'string' ? parsed.clarificationQuestion.trim() : '';
+    if (needsClarification && question) {
+        const messages = nextMessages();
+        messages.push({ role: 'assistant', content: question });
+        return { skillRoute: 'clarify', activatedSkill: null, messages };
+    }
+    const rawName = typeof parsed.activatedSkill === 'string' ? parsed.activatedSkill.trim() : '';
+    const params = parsed.params && typeof parsed.params === 'object' && !Array.isArray(parsed.params)
+        ? parsed.params
+        : undefined;
+    const skill = resolveSkillDefinition(defs, rawName);
+    if (!skill) {
+        const asked = Boolean(rawName && rawName !== 'none');
+        return {
+            skillRoute: 'none',
+            activatedSkill: null,
+            skillInput: params,
+            messages: nextMessages(),
+            unmatched: asked,
+        };
+    }
+    return {
+        skillRoute: 'skill',
+        activatedSkill: skill.skillId,
+        skillName: skill.name || skill.skillId,
+        activeSkillPrompt: buildSkillPrompt(skill, params),
+        skillInput: params,
+        messages: nextMessages(),
+    };
+}

package/dist/graph/nodes/tool-node.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ToolNode — Tool 执行节点
+ *
+ * 在 StateGraph 中作为 node function 注册，负责：
+ * 1. 从 state 中提取最后一条 assistant 消息的 toolCalls
+ * 2. 通过 ToolOrchestrator.executeAll() 并行执行所有 Tool 调用
+ * 3. 通过 ToolResultInjector 将执行结果注入 state
+ *
+ * @see design.md §1.4 ToolNode: LangGraph的ToolNode封装
+ * @see requirements.md Requirement 8 AC1, AC3, AC5
+ */
+import type { AuthContext } from '../../tool/tool-executor.interface.js';
+import type { ToolOrchestrator } from '../../tool/tool-orchestrator.js';
+import type { ToolResultInjector } from '../../tool/tool-result-injector.js';
+import type { HitlHandler } from '../hitl/hitl-handler.js';
+/**
+ * LangGraphState — LangGraph 内部状态（与 LLMNode 对齐）
+ */
+type LangGraphState = Record<string, unknown>;
+/**
+ * ToolNode — Tool 执行节点（封装 ToolOrchestrator）
+ *
+ * 职责：
+ * 1. 从 state.messages 中找到最后一条 assistant 消息的 toolCalls
+ * 2. 将 toolCalls 转换为 ToolCallRequest[]（附带 authContext）
+ * 3. 调用 orchestrator.executeAll() 并行执行
+ * 4. 调用 injector.injectResults() 将结果写回 state
+ * 5. 返回更新后的 state
+ *
+ * 支持多 Tool 并行调用，LLM 一次返回多个 tool_call 时全部并行执行。
+ */
+export interface ToolNodeProgress {
+    toolCallId: string;
+    toolName: string;
+    status: 'started' | 'completed' | 'error';
+    arguments?: Record<string, unknown>;
+    content?: string;
+    error?: string;
+    executionTime?: number;
+    node?: string;
+    skillId?: string;
+}
+export declare class ToolNode {
+    private readonly orchestrator;
+    private readonly injector;
+    private readonly defaultAuthContext;
+    private readonly onProgress?;
+    private readonly hitlHandler?;
+    private readonly nodeId?;
+    constructor(orchestrator: ToolOrchestrator, injector: ToolResultInjector, defaultAuthContext: AuthContext, onProgress?: ((data: ToolNodeProgress) => void) | undefined, hitlHandler?: HitlHandler | undefined, nodeId?: string | undefined);
+    /**
+     * execute — StateGraph 节点函数
+     *
+     * 提取 pending tool_calls → 并行执行 → 注入结果 → 返回更新 state
+     *
+     * @param state - 当前 LangGraph State
+     * @returns 包含 Tool 结果消息的更新 state
+     */
+    execute(state: LangGraphState): Promise<LangGraphState>;
+    /**
+     * 从 state 中提取 messages 数组
+     */
+    private extractMessages;
+    /**
+     * 从 messages 中找到最后一条 assistant 消息
+     */
+    private findLastAssistantMessage;
+    private buildAuthContext;
+    private shouldForceServer;
+    /**
+     * 将 LangGraphState 转换为 GraphState（供 injector 使用）
+     */
+    private toGraphState;
+}
+export {};