@gt-fe/eap-runtime 0.0.20 → 0.0.22

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

@@ -3,18 +3,21 @@
  *
  * 将 Skill DSL 编译为子图节点函数，嵌入父 Graph 执行。
  * 子图作为独立 StateGraph 编译，父图通过节点函数调用子图并合并输出。
+ * Skill 子图不得再含 type=subgraph（G-3 / B14）。
  *
  * @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 { assertSkillGraphHasNoSubgraphNodes } from './graph-nesting.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
 import { skillSpanFields, skillTraceIdentity } from './skill-entry-span.js';
 import { filterLoadedToolsForSkill, } from '../../tool/system-prompt-builder.js';
 import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { pickContextFields } from '../../token/context-window.js';
 import { assertSkillIoIfEnabled, coerceSkillInputFromMessages, } from '../../registry/skill-io-guard.js';
+import { isolatedSkillMessages, isolatedSkillOutput, } from './skill-isolate.js';
 /**
  * SubGraphCompiler — 子图编译器
  *
@@ -25,10 +28,12 @@ import { assertSkillIoIfEnabled, coerceSkillInputFromMessages, } from '../../reg
  * 4. 执行时，子图内部运行完整的 graph invoke 流程，输出合并回父图 state
  */
 export class SubGraphCompiler {
+    auditReporter;
     adapter;
     governanceClient;
     skillAuditRecorder;
-    constructor(adapter, governanceClient, skillAuditRecorder) {
+    constructor(adapter, governanceClient, skillAuditRecorder, auditReporter) {
+        this.auditReporter = auditReporter;
         this.adapter = adapter ?? new LangGraphAdapter();
         this.governanceClient = governanceClient;
         this.skillAuditRecorder = skillAuditRecorder;
@@ -39,14 +44,23 @@ export class SubGraphCompiler {
      * @param dsl - Skill 的 GraphDSL 定义
      * @param skillId - Skill 资源 ID（用于 checkPermission skill:use）
      */
-    compileSubGraph(dsl, skillId) {
+    compileSubGraph(dsl, skillId, options) {
+        assertSkillGraphHasNoSubgraphNodes(dsl, skillId ?? dsl.name);
         const adapter = this.adapter;
+        const isolateContext = options?.isolateContext === true;
         const resolvedSkillId = skillId ?? dsl.name ?? '';
         const subGraphNodeFn = async (state) => {
-            const executionContext = state['executionContext'];
-            if (executionContext) {
-                await assertSkillPermission(this.governanceClient, executionContext, resolvedSkillId);
-            }
+            const executionContext = state['executionContext'] ?? {
+                userId: String(state['userId'] ?? ''),
+                callerType: 'user',
+                roles: [],
+                permissions: [],
+                delegationToken: String(state['delegationToken'] ?? ''),
+                correlationId: String(state['correlationId'] ?? ''),
+            };
+            await assertSkillPermission(this.governanceClient, executionContext, resolvedSkillId, {
+                auditReporter: this.auditReporter,
+            });
             const existingSpanId = typeof state['skillSpanId'] === 'string' && state['skillSpanId']
                 ? state['skillSpanId']
                 : '';
@@ -119,26 +133,32 @@ export class SubGraphCompiler {
                 if (skillInfo) {
                     assertSkillIoIfEnabled(skillInfo, skillInput);
                 }
+                const parentMessages = 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'] }
+                        : {}),
+                }));
+                const subMessagesIn = isolateContext
+                    ? isolatedSkillMessages(parentMessages, skillInput)
+                    : parentMessages;
                 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,
+                    messages: subMessagesIn,
+                    // 同父 session；checkpointNs=父节点 id → 子图槽 thread_id#父节点id（HITL 同槽，含 isolate）。
+                    replaceCheckpointMessages: !isolateContext,
                     userId,
                     delegationToken,
                     agentCode,
                     taskId: state['taskId'],
                     correlationId: state['correlationId'],
                     sessionId: state['sessionId'],
+                    checkpointNs: options?.parentNodeId,
+                    skillIsolateContext: isolateContext || undefined,
                     executionContext: state['executionContext'],
                     loadedTools: scopedTools,
                     loadedSkills: state['loadedSkills'],
@@ -154,6 +174,8 @@ export class SubGraphCompiler {
                     lastSpanId: skillSpanId ?? state['lastSpanId'],
                     hitlChoice: state['hitlChoice'],
                     hitlRespondedBy: state['hitlRespondedBy'],
+                    toolSpanId: typeof state['toolSpanId'] === 'string' ? state['toolSpanId'] : undefined,
+                    hitlToolCallId: typeof state['hitlToolCallId'] === 'string' ? state['hitlToolCallId'] : undefined,
                 };
                 const result = await adapter.runIsolatedLlmStreamFlags(() => adapter.invoke(subGraph, subGraphState));
                 // 进程内调试记录；生产记录是上面的 skill Span
@@ -192,19 +214,28 @@ export class SubGraphCompiler {
                         ...(reasoningContent ? { reasoningContent } : {}),
                     },
                 });
-                const added = subMessages.slice(messages.length);
-                const outputMessages = added.length > 0
-                    ? added
-                    : result.output
-                        ? [{ role: 'assistant', content: result.output }]
-                        : [];
+                const added = subMessages.slice(subMessagesIn.length);
+                const outputMessages = isolateContext
+                    ? isolatedSkillOutput(added.length > 0
+                        ? added
+                        : result.output
+                            ? [{ role: 'assistant', content: result.output }]
+                            : [])
+                    : added.length > 0
+                        ? added
+                        : result.output
+                            ? [{ role: 'assistant', content: result.output }]
+                            : [];
                 const perNode = result.tokenUsage?.perNode;
                 const nestedLastSpanId = (typeof result.finalState?.lastSpanId === 'string' && result.finalState.lastSpanId) ||
                     skillSpanId ||
                     undefined;
+                const parentNodeId = options?.parentNodeId
+                    || (dsl.name ? `subgraph:${dsl.name}` : 'subgraph');
                 return {
                     messages: outputMessages,
-                    currentNode: `subgraph:${dsl.name}`,
+                    currentNode: parentNodeId,
+                    historyPath: [parentNodeId],
                     ...(nestedLastSpanId ? { lastSpanId: nestedLastSpanId } : {}),
                     ...(Array.isArray(perNode) && perNode.length > 0
                         ? {
@@ -224,15 +255,17 @@ export class SubGraphCompiler {
                 if (hitlPaused) {
                     throw err;
                 }
+                const failErr = err;
+                const failMessage = failErr instanceof Error ? failErr.message : String(failErr);
                 await auditCtx?.finish({
                     status: 'failed',
-                    errorMessage: err instanceof Error ? err.message : String(err),
+                    errorMessage: failMessage,
                 });
                 if (traceCollector && skillSpanId) {
                     try {
                         await traceCollector.completeNode(skillSpanId, {
                             status: 'failed',
-                            error: err instanceof Error ? err.message : String(err),
+                            error: failMessage,
                         });
                     }
                     catch (completeErr) {
@@ -247,10 +280,10 @@ export class SubGraphCompiler {
                     payload: {
                         skillId: resolvedSkillId,
                         skillName,
-                        error: err instanceof Error ? err.message : String(err),
+                        error: failMessage,
                     },
                 });
-                throw err;
+                throw failErr;
             }
         };
         return subGraphNodeFn;

package/dist/graph/contracts/executable-graph.d.ts

@@ -7,8 +7,14 @@
  * @see design.md §1.4 StateGraph Contract
  * @see requirements.md Requirement 1 AC1-AC2
  */
-import type { GraphDSL as BaseGraphDSL, GraphNode as BaseGraphNode, GraphEdge as BaseGraphEdge, GraphNodeType, GraphConfig } from '@gt-fe/eap-contracts';
-export type { GraphNodeType, GraphConfig };
+import type { GraphDSL as BaseGraphDSL, GraphNode as BaseGraphNode, GraphEdge as BaseGraphEdge, GraphNodeType as ContractsGraphNodeType, GraphConfig } from '@gt-fe/eap-contracts';
+export type { GraphConfig };
+/**
+ * GraphNodeType — runtime 侧扩展联合：contracts 官方包的 'rag' 类型尚未合入
+ * （客户 MR 跟进中），在此扩展使官方 contracts 零 patch 可用；
+ * contracts 合入后此扩展退化为无害超集，可直接删除回归 re-export。
+ */
+export type GraphNodeType = ContractsGraphNodeType | 'rag';
 /**
  * RuntimeGraphConfig — Runtime 层扩展的 Graph 配置
  *
@@ -26,7 +32,9 @@ export interface RuntimeGraphConfig extends GraphConfig {
  * - HITL 标记（interrupt_before / interrupt_after）
  * - 描述信息（调试/Trace 用）
  */
-export interface GraphNode extends BaseGraphNode {
+export interface GraphNode extends Omit<BaseGraphNode, 'type'> {
+    /** 节点类型（contracts 联合 + runtime 扩展 'rag'，见 GraphNodeType） */
+    type: GraphNodeType;
     /** 节点显示名称（调试/Trace 用） */
     label?: string;
     /** 节点描述 */
@@ -37,8 +45,6 @@ export interface GraphNode extends BaseGraphNode {
     interrupt?: NodeInterruptConfig;
     /** 子图引用 ID（type=subgraph 时必填） */
     subgraphId?: string;
-    /** 并行分支定义（type=parallel 时使用） */
-    branches?: string[];
 }
 /**
  * GraphEdge — 基础边定义
@@ -183,6 +189,10 @@ export interface GraphState {
     executionContext?: PlatformExecutionContext;
     /** ExecuteConfig.forceToolServer — 单次 invoke 强制走 Gateway 的 toolName */
     forceToolServer?: string[];
+    /** 请求级检索范围（前端圈定 fileIds/dirPaths；rag 节点读取，仅本地检索源生效） */
+    ragScope?: import('../../graph/nodes/rag/types.js').RagScope;
+    /** 会话级数据源勾选（数据源 id 列表；undefined = 全部启用） */
+    ragSources?: string[];
     /** GraphLoader 注入：toolName → 运行期 manifest 引用 */
     loadedTools?: import('../../tool/loaded-tool-definition.js').LoadedToolMap;
     /** GraphLoader 注入：已装配 Skill 列表 */
@@ -212,8 +222,20 @@ export interface GraphState {
      * 不入 Checkpoint。
      */
     traceCollector?: import('../../contracts/trace-collector.js').ITraceCollector;
+    /**
+     * 当前节点跑在 Skill 隔离子图内。为 true 时禁止 HITL interrupt
+     *（隔离不写父 session Checkpoint，确认态会丢）。
+     */
+    skillIsolateContext?: boolean;
     /** 当前 Skill 子图 createNode 返回的 span id；子图内 Tool span 的 parentNodeId */
     skillSpanId?: string;
+    /**
+     * HITL 续跑：暂停时已 create 的 tool Span id。
+     * 按 hitlToolCallId 复用，禁止再 createNode。
+     */
+    toolSpanId?: string;
+    /** 与 toolSpanId 配对的 toolCallId（同一 assistant 多 tool 时只复用这一次调用） */
+    hitlToolCallId?: string;
     /** 最近一次 createNode 的 span id；Checkpoint 引用挂在此 Span 上 */
     lastSpanId?: string;
     /**
@@ -221,6 +243,12 @@ export interface GraphState {
      * 仅 stream/invoke 入口使用，不入持久化语义。
      */
     replaceCheckpointMessages?: boolean;
+    /**
+     * 子图 invoke 写入 LangGraph `checkpoint_ns`。
+     * 父图为空；子图为父节点 id。存储槽与父 thread 分开，不覆盖父 latest。
+     * HITL interrupt 用同一槽；resume 返回给父图入口的 GraphState 不含本字段，也不含内层 historyPath / currentNode。
+     */
+    checkpointNs?: string;
     [key: string]: unknown;
 }
 /** Graph 内部消息格式 */

package/dist/graph/hitl/hitl-handler.d.ts

@@ -13,7 +13,7 @@
 import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
 import type { ITraceCollector } from '../../contracts/trace-collector.js';
 import type { ISSEEmitter } from '../../sse/contracts/sse-emitter.contract.js';
-import type { GraphState } from '../contracts/executable-graph.js';
+import type { GraphState, CheckpointData } from '../contracts/executable-graph.js';
 /** HITL 默认等待时长（毫秒）= 300 秒。SSE `hitl.waited.timeout` 对外用秒。 */
 export declare const DEFAULT_HITL_TIMEOUT_MS = 300000;
 /** 超时收口对外文案（Task / Trace / AppError）；枚举走 `hitl_timeout`。 */
@@ -106,6 +106,8 @@ export declare class HitlPausedError extends Error {
 export declare function unwrapHitlPaused(error: unknown): HitlPausedError | null;
 /** Checkpoint state 中持久化的 HITL 等待元数据（进程重启 / 无内存 Map 时冷恢复） */
 export declare const HITL_WAITING_STATE_KEY = "__hitlWaiting";
+/** 父槽上的指针：子图 HITL 的 waiting 在 `sessionId#父节点id`，冷恢复只带 sessionId 时跟随此键。 */
+export declare const HITL_WAITING_SLOT_KEY = "__hitlWaitingSlot";
 export interface PersistedHitlWaiting {
     taskId: string;
     threadId: string;
@@ -141,6 +143,12 @@ export declare function toHitlTimeoutMs(timeoutMs?: number): number;
 export declare function toHitlTimeoutSeconds(timeoutMs?: number): number;
 export declare function isHitlDeadlinePassed(persisted: Pick<PersistedHitlWaiting, 'deadlineAt'> | undefined, now?: number): boolean;
 export declare function readPersistedHitlWaiting(state: unknown): PersistedHitlWaiting | undefined;
+export declare function readHitlWaitingSlot(state: unknown): string | undefined;
+/** 父槽有 waiting 用父槽；否则跟随 `__hitlWaitingSlot` 到子图槽。 */
+export declare function loadHitlCheckpoint(saver: ICheckpointSaver, threadId: string): Promise<{
+    threadId: string;
+    checkpoint: CheckpointData | null;
+}>;
 /** 门面 stream / HTTP StreamOrchestrator / streamResumeHitl 共用 */
 export declare function buildHitlWaitedPayload(paused: HitlPausedError): {
     question: string;
@@ -177,9 +185,10 @@ export declare class HitlHandler {
     /**
      * 中断 Graph 执行，等待人工确认
      *
-     * 写入 `__hitlWaiting`（含 deadlineAt）到同一 thread 的 Checkpoint。
-     * 不保留 LangGraph `engineSnapshot`：子图与父图共用 session thread，
-     * resume 时用 GraphState 从父图入口重入（skillSpanId / hitlChoice 防重复 span）。
+     * 写入 `__hitlWaiting`（含 deadlineAt）到当前执行图的 Checkpoint 槽。
+     * 父图槽=sessionId；子图槽=sessionId#父节点id（与 LangGraph put 同一把钥匙）。
+     * 不保留 LangGraph `engineSnapshot`：resume 从父图入口重入
+     *（skillSpanId / hitlChoice 防重复 span；子图 resume 去掉 checkpointNs / 内层 historyPath / currentNode）。
      */
     interrupt(taskId: string, threadId: string, state: GraphState, config: HitlInterruptConfig, extras?: HitlInterruptExtras): Promise<void>;
     private interruptCore;

package/dist/graph/hitl/hitl-handler.js

@@ -118,6 +118,8 @@ export function unwrapHitlPaused(error) {
 }
 /** Checkpoint state 中持久化的 HITL 等待元数据（进程重启 / 无内存 Map 时冷恢复） */
 export const HITL_WAITING_STATE_KEY = '__hitlWaiting';
+/** 父槽上的指针：子图 HITL 的 waiting 在 `sessionId#父节点id`，冷恢复只带 sessionId 时跟随此键。 */
+export const HITL_WAITING_SLOT_KEY = '__hitlWaitingSlot';
 export function toHitlTimeoutMs(timeoutMs) {
     if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         return DEFAULT_HITL_TIMEOUT_MS;
@@ -142,6 +144,29 @@ export function readPersistedHitlWaiting(state) {
         return undefined;
     return raw;
 }
+export function readHitlWaitingSlot(state) {
+    if (!state || typeof state !== 'object')
+        return undefined;
+    const raw = state[HITL_WAITING_SLOT_KEY];
+    if (typeof raw === 'string' && raw.trim())
+        return raw.trim();
+    return undefined;
+}
+/** 父槽有 waiting 用父槽；否则跟随 `__hitlWaitingSlot` 到子图槽。 */
+export async function loadHitlCheckpoint(saver, threadId) {
+    const first = await saver.load(threadId);
+    if (readPersistedHitlWaiting(first?.state)) {
+        return { threadId, checkpoint: first };
+    }
+    const slot = readHitlWaitingSlot(first?.state);
+    if (slot && slot !== threadId) {
+        const nested = await saver.load(slot);
+        if (readPersistedHitlWaiting(nested?.state)) {
+            return { threadId: slot, checkpoint: nested };
+        }
+    }
+    return { threadId, checkpoint: first };
+}
 /** 门面 stream / HTTP StreamOrchestrator / streamResumeHitl 共用 */
 export function buildHitlWaitedPayload(paused) {
     return {
@@ -243,9 +268,10 @@ export class HitlHandler {
     /**
      * 中断 Graph 执行，等待人工确认
      *
-     * 写入 `__hitlWaiting`（含 deadlineAt）到同一 thread 的 Checkpoint。
-     * 不保留 LangGraph `engineSnapshot`：子图与父图共用 session thread，
-     * resume 时用 GraphState 从父图入口重入（skillSpanId / hitlChoice 防重复 span）。
+     * 写入 `__hitlWaiting`（含 deadlineAt）到当前执行图的 Checkpoint 槽。
+     * 父图槽=sessionId；子图槽=sessionId#父节点id（与 LangGraph put 同一把钥匙）。
+     * 不保留 LangGraph `engineSnapshot`：resume 从父图入口重入
+     *（skillSpanId / hitlChoice 防重复 span；子图 resume 去掉 checkpointNs / 内层 historyPath / currentNode）。
      */
     async interrupt(taskId, threadId, state, config, extras = {}) {
         const work = () => this.interruptCore(taskId, threadId, state, config, extras);
@@ -300,6 +326,28 @@ export class HitlHandler {
         };
         const persistedCheckpoint = stripCheckpointCollectors(checkpointData);
         await this.checkpointSaver.save(threadId, persistedCheckpoint);
+        const parentSessionId = typeof state.sessionId === 'string' && state.sessionId.trim()
+            ? state.sessionId.trim()
+            : '';
+        if (parentSessionId && threadId !== parentSessionId) {
+            const parent = await this.checkpointSaver.load(parentSessionId);
+            const pointerState = {
+                ...(parent?.state ?? { messages: [], userId: state.userId ?? '', sessionId: parentSessionId }),
+                [HITL_WAITING_SLOT_KEY]: threadId,
+            };
+            await this.checkpointSaver.save(parentSessionId, stripCheckpointCollectors({
+                checkpointId: parent?.checkpointId ?? `hitl-slot-${taskId}`,
+                threadId: parentSessionId,
+                currentNodeId: parent?.currentNodeId ?? '__hitl_waiting__',
+                historyPath: parent?.historyPath ?? [],
+                state: pointerState,
+                createdBy: parent?.createdBy ?? 'system',
+                createdAt: parent?.createdAt ?? now,
+                updatedBy: 'system',
+                updatedAt: now,
+                isDeleted: false,
+            }));
+        }
         const liveCollector = getExecutionTrace()?.collector;
         if (liveCollector) {
             this.waitingCollectors.set(taskId, liveCollector);
@@ -352,13 +400,14 @@ export class HitlHandler {
     async resume(taskId, choice, userId, threadIdHint) {
         return this.withTaskLock(taskId, async () => {
             let waiting = this.waitingTasks.get(taskId);
-            const threadId = waiting?.threadId ?? threadIdHint;
-            if (!threadId) {
+            const hinted = waiting?.threadId ?? threadIdHint;
+            if (!hinted) {
                 throw new HitlNotWaitingError(taskId);
             }
-            const checkpoint = await this.checkpointSaver.load(threadId);
+            const resolved = await loadHitlCheckpoint(this.checkpointSaver, hinted);
+            const checkpoint = resolved.checkpoint;
             if (!checkpoint) {
-                throw new Error(`Checkpoint not found for thread: ${threadId}`);
+                throw new Error(`Checkpoint not found for thread: ${resolved.threadId}`);
             }
             const persisted = readPersistedHitlWaiting(checkpoint.state);
             if (persisted?.timedOut) {
@@ -380,10 +429,19 @@ export class HitlHandler {
             const baseState = prepareHitlCheckpointState(checkpoint.state);
             const cleaned = { ...baseState };
             delete cleaned[HITL_WAITING_STATE_KEY];
+            const subgraphNs = typeof cleaned['checkpointNs'] === 'string' ? String(cleaned['checkpointNs']).trim() : '';
+            delete cleaned['checkpointNs'];
+            if (subgraphNs) {
+                // 父图入口重入：内层路径不能带进父图，否则 historyPath 混入子图节点。
+                delete cleaned['historyPath'];
+                delete cleaned['currentNode'];
+            }
             const resumedState = {
                 ...cleaned,
                 hitlChoice: choice,
                 hitlRespondedBy: userId,
+                ...(waiting.toolSpanId ? { toolSpanId: waiting.toolSpanId } : {}),
+                ...(waiting.toolCallId ? { hitlToolCallId: waiting.toolCallId } : {}),
             };
             const now = new Date().toISOString();
             await this.checkpointSaver.save(waiting.threadId, stripCheckpointCollectors({
@@ -393,6 +451,21 @@ export class HitlHandler {
                 updatedBy: userId,
                 updatedAt: now,
             }));
+            const parentSessionId = typeof resumedState.sessionId === 'string' && resumedState.sessionId.trim()
+                ? resumedState.sessionId.trim()
+                : '';
+            if (parentSessionId && waiting.threadId !== parentSessionId) {
+                const parent = await this.checkpointSaver.load(parentSessionId);
+                if (readHitlWaitingSlot(parent?.state) === waiting.threadId && parent) {
+                    const parentState = { ...parent.state };
+                    delete parentState[HITL_WAITING_SLOT_KEY];
+                    await this.checkpointSaver.save(parentSessionId, stripCheckpointCollectors({
+                        ...parent,
+                        state: parentState,
+                        updatedAt: now,
+                    }));
+                }
+            }
             const hitlSpanId = waiting.hitlSpanId ?? persisted?.hitlSpanId;
             const resumeTraceId = resolveTraceId(resumedState) ?? resolveTraceId(checkpoint.state);
             const resumeCtx = liveCollector && resumeTraceId

package/dist/graph/nodes/index.d.ts

@@ -1,2 +1,3 @@
 export { LLMNode, type LLMNodeConfig, type LLMResponse, type LLMNodeToolCall, type LLMChunk, type ILLMProvider, type LLMToolDefinition, } from './llm-node.js';
 export { ToolNode, type ToolNodeProgress } from './tool-node.js';
+export * from './rag/index.js';

package/dist/graph/nodes/index.js

@@ -1,2 +1,3 @@
 export { LLMNode, } from './llm-node.js';
 export { ToolNode } from './tool-node.js';
+export * from './rag/index.js';

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

@@ -10,6 +10,7 @@
  * @see requirements.md Requirement 1 AC6, Requirement 9
  */
 import type { NodeRetryConfig, GraphMessage } from '../contracts/executable-graph.js';
+import { type ExecutionInterceptors } from '../../execution/interceptors.js';
 /**
  * LLMNodeConfig — LLM 节点配置
  */
@@ -132,6 +133,7 @@ type LangGraphState = Record<string, unknown>;
  * 5. 将 LLM 响应追加到 state.messages 并返回
  */
 export declare class LLMNode {
+    private readonly interceptors?;
     private readonly config;
     private readonly provider;
     private readonly retryConfig;
@@ -145,7 +147,7 @@ export declare class LLMNode {
      * @param streaming - 是否启用流式输出（默认 false）
      * @param onChunk - 流式模式下每个文本片段回调（用于 SSE response.chunk）
      */
-    constructor(nodeId: string, config: LLMNodeConfig, provider: ILLMProvider, streaming?: boolean, onChunk?: (chunk: string) => void);
+    constructor(nodeId: string, config: LLMNodeConfig, provider: ILLMProvider, streaming?: boolean, onChunk?: (chunk: string) => void, interceptors?: Pick<ExecutionInterceptors, "beforeModel" | "afterModel"> | undefined);
     /**
      * execute — StateGraph 节点函数
      *

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

@@ -12,6 +12,8 @@
 import { formatUnknownError } from '../../utils/format-error.js';
 import { buildContextUsage, turnSectionChars } from '../../token/context-window.js';
 import { isAbortError } from '../../tool/timeout.js';
+import { emitRuntimeLog } from '../../common/logger.js';
+import { decideBeforeModel, } from '../../execution/interceptors.js';
 // ─────────────────────────────────────────────
 // Default retry config
 // ─────────────────────────────────────────────
@@ -38,6 +40,7 @@ const DEFAULT_RETRY_CONFIG = {
  * 5. 将 LLM 响应追加到 state.messages 并返回
  */
 export class LLMNode {
+    interceptors;
     config;
     provider;
     retryConfig;
@@ -51,7 +54,8 @@ export class LLMNode {
      * @param streaming - 是否启用流式输出（默认 false）
      * @param onChunk - 流式模式下每个文本片段回调（用于 SSE response.chunk）
      */
-    constructor(nodeId, config, provider, streaming = false, onChunk) {
+    constructor(nodeId, config, provider, streaming = false, onChunk, interceptors) {
+        this.interceptors = interceptors;
         this.nodeId = nodeId;
         this.config = config;
         this.provider = provider;
@@ -71,10 +75,30 @@ export class LLMNode {
         const messages = this.extractMessages(state);
         // 注入 system prompt
         const messagesWithSystem = this.prependSystemPrompt(messages);
+        const modelInput = {
+            messages: messagesWithSystem,
+            config: this.config,
+            nodeId: this.nodeId,
+        };
+        const gate = await decideBeforeModel(this.interceptors?.beforeModel, modelInput);
+        if (gate.action === 'deny') {
+            throw new Error(gate.reason);
+        }
+        const messagesForModel = gate.messages ?? messagesWithSystem;
         const startedAt = Date.now();
         // 带重试的 LLM 调用
-        const response = await this.invokeWithRetry(messagesWithSystem);
+        const response = await this.invokeWithRetry(messagesForModel);
         const durationMs = Date.now() - startedAt;
+        try {
+            await this.interceptors?.afterModel?.({ ...modelInput, messages: messagesForModel }, response);
+        }
+        catch (err) {
+            emitRuntimeLog('warn', 'runtime.intercept', 'afterModel failed', {
+                event: 'runtime.intercept.after_model_failed',
+                nodeId: this.nodeId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
         // 构建 assistant message（保留 reasoningContent 供后续 HTTP 回传）
         const assistantMessage = {
             role: 'assistant',

package/dist/graph/nodes/rag/dedup.d.ts

@@ -0,0 +1,20 @@
+/**
+ * dedup — 确定性去重（纯函数，不经 LLM）
+ *
+ * 精确去重（源内、fuse 前）：sourceId:rawId + 归一化 content hash。
+ * 约束：入参须先经收集侧（react-loop pushDocs）消除"同 id 不同 content"撞号
+ * （重编号 `${rawId}#r${n}`）——本函数 id 命中即弃仅对真重复成立；
+ * fuse 的跨源键 sourceId:rawId 同样依赖该唯一性。
+ * 近重去重（融合后、降噪判定前，M4）：字符 3-gram Jaccard 超 nearDupThreshold
+ * 判近重，保留序列靠前者（design-v2 §6.3 ①；跨源候选集几乎不重叠，属低频兜底）。
+ */
+import type { RetrievalDoc } from './types.js';
+export declare function dedupExact(docs: RetrievalDoc[]): RetrievalDoc[];
+/**
+ * 归一化内容相等（与 dedupExact 内容去重同口径）："重复"判定单一出处——
+ * 收集侧（react-loop pushDocs）跳过同 id 真重复时必须与融合前去重用同一口径，
+ * 两处口径分叉会导致同 id 同排版差异的文档一处跳过一处保留。
+ */
+export declare function sameContent(a: string, b: string): boolean;
+/** 近重去重：字符 n-gram Jaccard 超阈值即判近重，保留序列靠前者 */
+export declare function dedupNearDup(docs: RetrievalDoc[], threshold?: number): RetrievalDoc[];

package/dist/graph/nodes/rag/dedup.js

@@ -0,0 +1,77 @@
+/**
+ * dedup — 确定性去重（纯函数，不经 LLM）
+ *
+ * 精确去重（源内、fuse 前）：sourceId:rawId + 归一化 content hash。
+ * 约束：入参须先经收集侧（react-loop pushDocs）消除"同 id 不同 content"撞号
+ * （重编号 `${rawId}#r${n}`）——本函数 id 命中即弃仅对真重复成立；
+ * fuse 的跨源键 sourceId:rawId 同样依赖该唯一性。
+ * 近重去重（融合后、降噪判定前，M4）：字符 3-gram Jaccard 超 nearDupThreshold
+ * 判近重，保留序列靠前者（design-v2 §6.3 ①；跨源候选集几乎不重叠，属低频兜底）。
+ */
+import { createHash } from 'node:crypto';
+export function dedupExact(docs) {
+    const seenIds = new Set();
+    const seenContent = new Set();
+    const out = [];
+    for (const d of docs) {
+        const idKey = `${d.sourceId}:${d.rawId}`;
+        const contentKey = hashContent(d.content);
+        if (seenIds.has(idKey) || seenContent.has(contentKey))
+            continue;
+        seenIds.add(idKey);
+        seenContent.add(contentKey);
+        out.push(d);
+    }
+    return out;
+}
+function hashContent(content) {
+    // 归一化：压空白后取 hash，挡"内容相同仅排版不同"
+    const normalized = content.replace(/\s+/g, ' ').trim().toLowerCase();
+    return createHash('sha1').update(normalized).digest('hex');
+}
+/**
+ * 归一化内容相等（与 dedupExact 内容去重同口径）："重复"判定单一出处——
+ * 收集侧（react-loop pushDocs）跳过同 id 真重复时必须与融合前去重用同一口径，
+ * 两处口径分叉会导致同 id 同排版差异的文档一处跳过一处保留。
+ */
+export function sameContent(a, b) {
+    return hashContent(a) === hashContent(b);
+}
+/** 近重去重：字符 n-gram Jaccard 超阈值即判近重，保留序列靠前者 */
+export function dedupNearDup(docs, threshold = 0.8) {
+    const kept = [];
+    const keptGrams = [];
+    for (const d of docs) {
+        const grams = charGrams(d.content);
+        let near = false;
+        for (const g of keptGrams) {
+            if (jaccard(grams, g) > threshold) {
+                near = true;
+                break;
+            }
+        }
+        if (near)
+            continue;
+        kept.push(d);
+        keptGrams.push(grams);
+    }
+    return kept;
+}
+const NGRAM_SIZE = 3;
+function charGrams(content) {
+    const norm = content.replace(/\s+/g, ' ').trim();
+    const grams = new Set();
+    for (let i = 0; i + NGRAM_SIZE <= norm.length; i++) {
+        grams.add(norm.slice(i, i + NGRAM_SIZE));
+    }
+    return grams;
+}
+function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}