@gt-fe/eap-runtime 0.0.8

package/dist/graph/adapters/subgraph-compiler.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SubGraphCompiler — 子图嵌套编译器
+ *
+ * 将 Skill DSL 编译为子图节点函数，嵌入父 Graph 执行。
+ * 子图作为独立 StateGraph 编译，父图通过节点函数调用子图并合并输出。
+ *
+ * @see design.md §1.4 子图嵌套: Skill作为子图嵌入主Graph
+ * @see requirements.md Requirement 1 AC2 — 子图嵌套（Skill作为子图）
+ */
+import type { NodeFunction } from '@langchain/langgraph';
+import type { GraphDSL } from '../contracts/executable-graph.js';
+import type { IGovernanceClient } from '../../governance/governance-client.js';
+import { LangGraphAdapter } from './langgraph.adapter.js';
+import type { SkillAuditRecorder } from '../skill-audit-recorder.js';
+/** LangGraph 内部状态类型 */
+type LangGraphState = Record<string, unknown>;
+/**
+ * SubGraphCompiler — 子图编译器
+ *
+ * 职责：
+ * 1. 接收 Skill 的 GraphDSL 定义
+ * 2. 通过 LangGraphAdapter 将其编译为独立的 ExecutableGraph
+ * 3. 返回一个 NodeFunction，父图将此函数当作普通节点执行
+ * 4. 执行时，子图内部运行完整的 graph invoke 流程，输出合并回父图 state
+ */
+export declare class SubGraphCompiler {
+    private readonly adapter;
+    private readonly governanceClient?;
+    private readonly skillAuditRecorder?;
+    constructor(adapter?: LangGraphAdapter, governanceClient?: IGovernanceClient, skillAuditRecorder?: SkillAuditRecorder);
+    /**
+     * 将 Skill DSL 编译为可嵌入父图的 NodeFunction
+     *
+     * @param dsl - Skill 的 GraphDSL 定义
+     * @param skillId - Skill 资源 ID（用于 checkPermission skill:use）
+     */
+    compileSubGraph(dsl: GraphDSL, skillId?: string): NodeFunction<LangGraphState>;
+}
+export {};

package/dist/graph/adapters/subgraph-compiler.js

@@ -0,0 +1,248 @@
+/**
+ * SubGraphCompiler — 子图嵌套编译器
+ *
+ * 将 Skill DSL 编译为子图节点函数，嵌入父 Graph 执行。
+ * 子图作为独立 StateGraph 编译，父图通过节点函数调用子图并合并输出。
+ *
+ * @see design.md §1.4 子图嵌套: Skill作为子图嵌入主Graph
+ * @see requirements.md Requirement 1 AC2 — 子图嵌套（Skill作为子图）
+ */
+import { assertSkillPermission } from '../../governance/permission-guard.js';
+import { LangGraphAdapter } from './langgraph.adapter.js';
+import { resolveTraceId } from '../../common/trace-id.js';
+import { filterLoadedToolsForSkill, } from '../../tool/system-prompt-builder.js';
+import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
+import { assertSkillIoIfEnabled, coerceSkillInputFromMessages, } from '../../registry/skill-io-guard.js';
+/**
+ * SubGraphCompiler — 子图编译器
+ *
+ * 职责：
+ * 1. 接收 Skill 的 GraphDSL 定义
+ * 2. 通过 LangGraphAdapter 将其编译为独立的 ExecutableGraph
+ * 3. 返回一个 NodeFunction，父图将此函数当作普通节点执行
+ * 4. 执行时，子图内部运行完整的 graph invoke 流程，输出合并回父图 state
+ */
+export class SubGraphCompiler {
+    adapter;
+    governanceClient;
+    skillAuditRecorder;
+    constructor(adapter, governanceClient, skillAuditRecorder) {
+        this.adapter = adapter ?? new LangGraphAdapter();
+        this.governanceClient = governanceClient;
+        this.skillAuditRecorder = skillAuditRecorder;
+    }
+    /**
+     * 将 Skill DSL 编译为可嵌入父图的 NodeFunction
+     *
+     * @param dsl - Skill 的 GraphDSL 定义
+     * @param skillId - Skill 资源 ID（用于 checkPermission skill:use）
+     */
+    compileSubGraph(dsl, skillId) {
+        const adapter = this.adapter;
+        const resolvedSkillId = skillId ?? dsl.name ?? '';
+        const subGraphNodeFn = async (state) => {
+            const executionContext = state['executionContext'];
+            if (executionContext) {
+                await assertSkillPermission(this.governanceClient, executionContext, resolvedSkillId);
+            }
+            const existingSpanId = typeof state['skillSpanId'] === 'string' && state['skillSpanId']
+                ? state['skillSpanId']
+                : '';
+            const resuming = Boolean(existingSpanId);
+            const auditCtx = resuming
+                ? undefined
+                : this.skillAuditRecorder?.startInvocation({
+                    skillId: resolvedSkillId,
+                    skillName: dsl.name,
+                    agentCode: (state['agentCode'] ?? state['agentId']),
+                    userId: state['userId'] ?? '',
+                    taskId: state['taskId'],
+                    correlationId: state['correlationId'],
+                });
+            const traceCollector = state['traceCollector'];
+            const traceId = resolveTraceId(state);
+            const skillName = dsl.name || resolvedSkillId;
+            if (!resuming) {
+                adapter.emitStreamEvent({
+                    type: 'skill.started',
+                    taskId: state['taskId'],
+                    correlationId: state['correlationId'],
+                    timestamp: new Date().toISOString(),
+                    payload: {
+                        skillId: resolvedSkillId,
+                        skillName,
+                    },
+                });
+            }
+            let skillSpanId = existingSpanId || null;
+            if (!resuming && traceCollector && traceId) {
+                try {
+                    skillSpanId = await traceCollector.createNode({
+                        traceId,
+                        name: resolvedSkillId || dsl.name || 'skill',
+                        type: 'skill',
+                        agentCode: state['agentCode'] ?? state['agentId'],
+                        metadata: { skillId: resolvedSkillId, taskId: state['taskId'], correlationId: state['correlationId'] },
+                    });
+                }
+                catch {
+                    skillSpanId = null;
+                }
+            }
+            try {
+                // 1. 编译子图（每次执行时编译，确保子图实例独立）
+                const subGraph = await adapter.buildGraph(dsl);
+                // 2. 从父 state 提取 messages 和上下文，构造子图输入
+                const messages = Array.isArray(state['messages']) ? state['messages'] : [];
+                const userId = state['userId'] ?? '';
+                const delegationToken = state['delegationToken'];
+                const agentCode = state['agentCode'] ?? state['agentId'];
+                const defs = state['skillDefinitions'];
+                const skillInfo = resolvedSkillId ? defs?.[resolvedSkillId] : undefined;
+                const skillPrompt = skillInfo?.prompt;
+                const parentTools = state['loadedTools'];
+                const scopedTools = filterLoadedToolsForSkill(parentTools, skillInfo);
+                const skillInput = skillInfo
+                    ? coerceSkillInputFromMessages(skillInfo, state['skillInput'], messages)
+                    : state['skillInput'];
+                if (skillInfo) {
+                    assertSkillIoIfEnabled(skillInfo, skillInput);
+                }
+                const subGraphState = {
+                    messages: messages.map((msg) => ({
+                        role: msg['role'] ?? 'user',
+                        content: msg['content'] ?? '',
+                        toolCalls: msg['tool_calls'] ?? msg['toolCalls'],
+                        ...(typeof msg['toolCallId'] === 'string' ? { toolCallId: msg['toolCallId'] } : {}),
+                        ...(typeof msg['toolName'] === 'string' ? { toolName: msg['toolName'] } : {}),
+                        ...(typeof msg['success'] === 'boolean' ? { success: msg['success'] } : {}),
+                        ...(typeof msg['reasoningContent'] === 'string'
+                            ? { reasoningContent: msg['reasoningContent'] }
+                            : {}),
+                    })),
+                    // 子图与父图共用 session thread；入口必须 __set，否则 checkpointer 会把父图 messages 再 append 一遍
+                    replaceCheckpointMessages: true,
+                    userId,
+                    delegationToken,
+                    agentCode,
+                    taskId: state['taskId'],
+                    correlationId: state['correlationId'],
+                    sessionId: state['sessionId'],
+                    executionContext: state['executionContext'],
+                    loadedTools: scopedTools,
+                    loadedSkills: state['loadedSkills'],
+                    skillDefinitions: defs,
+                    activeSkillPrompt: skillPrompt,
+                    activatedSkill: resolvedSkillId || undefined,
+                    skillInput,
+                    traceId,
+                    traceCollector,
+                    skillSpanId: skillSpanId ?? undefined,
+                    hitlChoice: state['hitlChoice'],
+                    hitlRespondedBy: state['hitlRespondedBy'],
+                };
+                const result = await adapter.runIsolatedLlmStreamFlags(() => adapter.invoke(subGraph, subGraphState));
+                // RT-6: 记录成功
+                await auditCtx?.finish({
+                    status: 'success',
+                    tokenUsage: result.tokenUsage,
+                });
+                if (traceCollector && skillSpanId) {
+                    try {
+                        await traceCollector.completeNode(skillSpanId, {
+                            status: 'completed',
+                            output: result.output,
+                            inputTokens: result.tokenUsage?.input,
+                            outputTokens: result.tokenUsage?.output,
+                            totalTokens: result.tokenUsage?.total,
+                        });
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                // 4. 只回写子图本步新增消息（含内部 tool 回合），禁止把入口历史再 append
+                const subMessages = Array.isArray(result.finalState?.messages)
+                    ? result.finalState.messages
+                    : [];
+                const reasoningContent = lastAssistantReasoning(subMessages);
+                adapter.emitStreamEvent({
+                    type: 'skill.completed',
+                    taskId: state['taskId'],
+                    correlationId: state['correlationId'],
+                    timestamp: new Date().toISOString(),
+                    payload: {
+                        skillId: resolvedSkillId,
+                        skillName,
+                        output: result.output,
+                        ...(reasoningContent ? { reasoningContent } : {}),
+                    },
+                });
+                const added = subMessages.slice(messages.length);
+                const outputMessages = added.length > 0
+                    ? added
+                    : result.output
+                        ? [{ role: 'assistant', content: result.output }]
+                        : [];
+                const perNode = result.tokenUsage?.perNode;
+                return {
+                    messages: outputMessages,
+                    currentNode: `subgraph:${dsl.name}`,
+                    ...(Array.isArray(perNode) && perNode.length > 0
+                        ? {
+                            __llmTokenUsage: perNode.map((u) => ({
+                                nodeId: u.nodeId,
+                                model: u.model,
+                                inputTokens: u.inputTokens,
+                                outputTokens: u.outputTokens,
+                            })),
+                        }
+                        : {}),
+                };
+            }
+            catch (err) {
+                const hitlPaused = unwrapHitlPaused(err);
+                if (hitlPaused) {
+                    throw err;
+                }
+                await auditCtx?.finish({
+                    status: 'failed',
+                    errorMessage: err instanceof Error ? err.message : String(err),
+                });
+                if (traceCollector && skillSpanId) {
+                    try {
+                        await traceCollector.completeNode(skillSpanId, {
+                            status: 'failed',
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                adapter.emitStreamEvent({
+                    type: 'skill.failed',
+                    taskId: state['taskId'],
+                    correlationId: state['correlationId'],
+                    timestamp: new Date().toISOString(),
+                    payload: {
+                        skillId: resolvedSkillId,
+                        skillName,
+                        error: err instanceof Error ? err.message : String(err),
+                    },
+                });
+                throw err;
+            }
+        };
+        return subGraphNodeFn;
+    }
+}
+function lastAssistantReasoning(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const content = messages[i]?.reasoningContent;
+        if (messages[i]?.role === 'assistant' && typeof content === 'string' && content) {
+            return content;
+        }
+    }
+    return undefined;
+}

package/dist/graph/condition-evaluator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ConditionEvaluator — Graph 条件路由评估器
+ *
+ * 支持三种条件评估模式：
+ * 1. **stateField** — 读取 state 中指定字段的值，与分支 value 匹配
+ * 2. **expression** — 简单表达式求值（支持 ===, !==, >, <, >=, <=, includes, truthy/falsy）
+ * 3. **custom** — 注册自定义评估函数
+ *
+ * @see executable-graph.ts ConditionalEdge.conditionFn
+ */
+type LangGraphState = Record<string, unknown>;
+/**
+ * 自定义条件评估函数签名
+ */
+export type ConditionEvaluatorFn = (state: LangGraphState) => string | Promise<string>;
+/**
+ * ConditionEvaluator — 条件路由评估服务
+ *
+ * 管理已注册的自定义评估函数，并提供状态字段读取和表达式求值能力。
+ */
+export declare class ConditionEvaluator {
+    private readonly customEvaluators;
+    /**
+     * 注册自定义条件评估函数
+     */
+    register(name: string, fn: ConditionEvaluatorFn): void;
+    /**
+     * 评估条件表达式，返回匹配的分支值
+     *
+     * @param conditionExpr - 条件表达式字符串（DSL 中 conditionFn 字段）
+     * @param state - 当前 Graph State
+     * @param branches - 可用的分支值列表
+     * @param fallback - 默认分支值
+     * @returns 匹配的分支值
+     */
+    evaluate(conditionExpr: string | undefined, state: LangGraphState, branches: string[], fallback: string): Promise<string>;
+    /**
+     * 从 state 中按路径读取值（支持嵌套路径如 `a.b.c`）
+     */
+    readStatePath(state: LangGraphState, path: string): unknown;
+    /**
+     * 简单表达式求值
+     *
+     * 支持格式：
+     * - `field === 'value'`
+     * - `field !== 'value'`
+     * - `field > number`
+     * - `field includes 'substring'`
+     * - `field`（truthy 检查）
+     */
+    private evaluateExpression;
+    /**
+     * 解析字面量值（字符串、数字、布尔）
+     */
+    private parseLiteral;
+}
+export {};

package/dist/graph/condition-evaluator.js

@@ -0,0 +1,162 @@
+/**
+ * ConditionEvaluator — Graph 条件路由评估器
+ *
+ * 支持三种条件评估模式：
+ * 1. **stateField** — 读取 state 中指定字段的值，与分支 value 匹配
+ * 2. **expression** — 简单表达式求值（支持 ===, !==, >, <, >=, <=, includes, truthy/falsy）
+ * 3. **custom** — 注册自定义评估函数
+ *
+ * @see executable-graph.ts ConditionalEdge.conditionFn
+ */
+/**
+ * ConditionEvaluator — 条件路由评估服务
+ *
+ * 管理已注册的自定义评估函数，并提供状态字段读取和表达式求值能力。
+ */
+export class ConditionEvaluator {
+    customEvaluators = new Map();
+    /**
+     * 注册自定义条件评估函数
+     */
+    register(name, fn) {
+        this.customEvaluators.set(name, fn);
+    }
+    /**
+     * 评估条件表达式，返回匹配的分支值
+     *
+     * @param conditionExpr - 条件表达式字符串（DSL 中 conditionFn 字段）
+     * @param state - 当前 Graph State
+     * @param branches - 可用的分支值列表
+     * @param fallback - 默认分支值
+     * @returns 匹配的分支值
+     */
+    async evaluate(conditionExpr, state, branches, fallback) {
+        if (!conditionExpr) {
+            // 无表达式时，尝试从 state.__conditionResult 读取（condition 节点写入）
+            const stateResult = this.readStatePath(state, '__conditionResult');
+            if (stateResult !== undefined && branches.includes(String(stateResult))) {
+                return String(stateResult);
+            }
+            return fallback;
+        }
+        // 1. 检查是否为已注册的自定义函数名
+        const customFn = this.customEvaluators.get(conditionExpr);
+        if (customFn) {
+            const result = await customFn(state);
+            if (branches.includes(result))
+                return result;
+            // afterSkillRoute 返回 skillId；图可用精确边，或用 "skill" 兜底所有命中
+            if (conditionExpr === 'afterSkillRoute' &&
+                result !== 'none' &&
+                result !== 'clarify' &&
+                branches.includes('skill')) {
+                return 'skill';
+            }
+            return fallback;
+        }
+        // 2. 检查是否为 stateField 引用（格式：`state.fieldName` 或 `field.subField`）
+        if (conditionExpr.startsWith('state.') || !conditionExpr.includes(' ')) {
+            const path = conditionExpr.startsWith('state.')
+                ? conditionExpr.slice(6)
+                : conditionExpr;
+            const value = this.readStatePath(state, path);
+            if (value !== undefined) {
+                const strValue = String(value);
+                return branches.includes(strValue) ? strValue : fallback;
+            }
+            return fallback;
+        }
+        // 3. 简单表达式求值
+        const result = this.evaluateExpression(conditionExpr, state, branches);
+        return result ?? fallback;
+    }
+    /**
+     * 从 state 中按路径读取值（支持嵌套路径如 `a.b.c`）
+     */
+    readStatePath(state, path) {
+        const parts = path.split('.');
+        let current = state;
+        for (const part of parts) {
+            if (current === null || current === undefined)
+                return undefined;
+            if (typeof current === 'object') {
+                current = current[part];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return current;
+    }
+    /**
+     * 简单表达式求值
+     *
+     * 支持格式：
+     * - `field === 'value'`
+     * - `field !== 'value'`
+     * - `field > number`
+     * - `field includes 'substring'`
+     * - `field`（truthy 检查）
+     */
+    evaluateExpression(expr, state, branches) {
+        const trimmed = expr.trim();
+        // 二元操作符匹配
+        const binaryOps = [
+            { op: '===', fn: (a, b) => a === b },
+            { op: '!==', fn: (a, b) => a !== b },
+            { op: '>=', fn: (a, b) => Number(a) >= Number(b) },
+            { op: '<=', fn: (a, b) => Number(a) <= Number(b) },
+            { op: '>', fn: (a, b) => Number(a) > Number(b) },
+            { op: '<', fn: (a, b) => Number(a) < Number(b) },
+            { op: ' includes ', fn: (a, b) => String(a).includes(String(b)) },
+        ];
+        for (const { op, fn } of binaryOps) {
+            const idx = trimmed.indexOf(op);
+            if (idx > 0) {
+                const leftPath = trimmed.slice(0, idx).trim();
+                const rightRaw = trimmed.slice(idx + op.length).trim();
+                const leftValue = this.readStatePath(state, leftPath);
+                const rightValue = this.parseLiteral(rightRaw);
+                const result = fn(leftValue, rightValue);
+                const resultStr = String(result);
+                return branches.includes(resultStr) ? resultStr : undefined;
+            }
+        }
+        // 无操作符：truthy 检查，返回字段值
+        const value = this.readStatePath(state, trimmed);
+        if (value !== undefined) {
+            const strValue = String(value);
+            if (branches.includes(strValue))
+                return strValue;
+            // truthy/falsy → true/false
+            const boolStr = String(!!value);
+            if (branches.includes(boolStr))
+                return boolStr;
+        }
+        return undefined;
+    }
+    /**
+     * 解析字面量值（字符串、数字、布尔）
+     */
+    parseLiteral(raw) {
+        // 带引号的字符串
+        if ((raw.startsWith("'") && raw.endsWith("'")) || (raw.startsWith('"') && raw.endsWith('"'))) {
+            return raw.slice(1, -1);
+        }
+        // 布尔
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        if (raw === 'null')
+            return null;
+        if (raw === 'undefined')
+            return undefined;
+        // 数字
+        const num = Number(raw);
+        if (!isNaN(num))
+            return num;
+        // 其他视为字符串
+        return raw;
+    }
+}