@gt-fe/eap-runtime 0.0.19 → 0.0.21

package/dist/graph/adapters/skill-read.d.ts

@@ -2,6 +2,16 @@ export interface SkillDirRef {
     skillId: string;
     bundlePath: string;
 }
+/** 技能包落点：Agent 预装 / 用户装配 / 开发态 overlay。 */
+export type SkillSpace = 'agent' | 'user' | 'local';
+/**
+ * 按实际 bundle 路径判定空间。有 agentDir 时相对预装根与 users/ 判定；
+ * 否则看路径段 `preinstall/skills` / `users/<id>/skills`。
+ */
+export declare function classifySkillSpace(bundleOrFilePath: string, opts?: {
+    agentDir?: string;
+    userId?: string;
+}): SkillSpace | undefined;
 /**
  * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
  */

package/dist/graph/adapters/skill-read.js

@@ -33,6 +33,39 @@ function skillIdFromSkillsSegment(norm) {
     const match = norm.match(/(?:^|\/)(?:preinstall\/)?skills\/([^/]+)(?:\/|$)/i);
     return match?.[1] ?? '';
 }
+/**
+ * 按实际 bundle 路径判定空间。有 agentDir 时相对预装根与 users/ 判定；
+ * 否则看路径段 `preinstall/skills` / `users/<id>/skills`。
+ */
+export function classifySkillSpace(bundleOrFilePath, opts) {
+    if (!bundleOrFilePath)
+        return undefined;
+    const target = normalizeForMatch(bundleOrFilePath);
+    const agentDir = opts?.agentDir?.trim();
+    if (agentDir) {
+        const root = normalizeForMatch(agentDir);
+        const pre = `${root}/preinstall/skills`;
+        if (target === pre || target.startsWith(`${pre}/`))
+            return 'agent';
+        const uid = opts?.userId?.trim();
+        if (uid) {
+            const user = `${root}/users/${uid}/skills`;
+            if (target === user || target.startsWith(`${user}/`))
+                return 'user';
+        }
+        if (new RegExp(`^${escapeRegExp(root)}/users/[^/]+/skills(/|$)`).test(target))
+            return 'user';
+        return 'local';
+    }
+    if (/(^|\/)preinstall\/skills(\/|$)/i.test(target))
+        return 'agent';
+    if (/(^|\/)users\/[^/]+\/skills(\/|$)/i.test(target))
+        return 'user';
+    return undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
  */

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

@@ -3,6 +3,7 @@
  *
  * 将 Skill DSL 编译为子图节点函数，嵌入父 Graph 执行。
  * 子图作为独立 StateGraph 编译，父图通过节点函数调用子图并合并输出。
+ * Skill 子图不得再含 type=subgraph（G-3 / B14）。
  *
  * @see design.md §1.4 子图嵌套: Skill作为子图嵌入主Graph
  * @see requirements.md Requirement 1 AC2 — 子图嵌套（Skill作为子图）
@@ -24,16 +25,20 @@ type LangGraphState = Record<string, unknown>;
  * 4. 执行时，子图内部运行完整的 graph invoke 流程，输出合并回父图 state
  */
 export declare class SubGraphCompiler {
+    private readonly auditReporter?;
     private readonly adapter;
     private readonly governanceClient?;
     private readonly skillAuditRecorder?;
-    constructor(adapter?: LangGraphAdapter, governanceClient?: IGovernanceClient, skillAuditRecorder?: SkillAuditRecorder);
+    constructor(adapter?: LangGraphAdapter, governanceClient?: IGovernanceClient, skillAuditRecorder?: SkillAuditRecorder, auditReporter?: import("../../governance/audit-reporter.js").IAuditReporter | undefined);
     /**
      * 将 Skill DSL 编译为可嵌入父图的 NodeFunction
      *
      * @param dsl - Skill 的 GraphDSL 定义
      * @param skillId - Skill 资源 ID（用于 checkPermission skill:use）
      */
-    compileSubGraph(dsl: GraphDSL, skillId?: string): NodeFunction<LangGraphState>;
+    compileSubGraph(dsl: GraphDSL, skillId?: string, options?: {
+        isolateContext?: boolean;
+        parentNodeId?: string;
+    }): NodeFunction<LangGraphState>;
 }
 export {};

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

@@ -3,17 +3,22 @@
  *
  * 将 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 { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 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, SKILL_ISOLATE_HITL_MESSAGE, } from './skill-isolate.js';
 /**
  * SubGraphCompiler — 子图编译器
  *
@@ -24,10 +29,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;
@@ -38,14 +45,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']
                 : '';
@@ -63,6 +79,7 @@ export class SubGraphCompiler {
             // 用父图这次调用上的 collector；内层 invoke 只补 collector/traceId，沿用外层流式袋。
             const { collector: traceCollector, traceId } = resolveExecutionTrace(state);
             const skillName = dsl.name || resolvedSkillId;
+            const identity = skillTraceIdentity(state, resolvedSkillId);
             if (!resuming) {
                 adapter.emitStreamEvent({
                     type: 'skill.started',
@@ -71,19 +88,27 @@ export class SubGraphCompiler {
                     timestamp: new Date().toISOString(),
                     payload: {
                         skillId: resolvedSkillId,
-                        skillName,
+                        skillName: identity.skillName || skillName,
+                        ...(identity.skillSpace ? { skillSpace: identity.skillSpace } : {}),
+                        ...(identity.skillVersion ? { skillVersion: identity.skillVersion } : {}),
                     },
                 });
             }
             let skillSpanId = existingSpanId || null;
             if (!resuming && traceCollector && traceId) {
                 try {
+                    const fields = skillSpanFields(identity, { source: 'subgraph' });
                     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'] },
+                        ...(fields.version ? { version: fields.version } : {}),
+                        input: fields.input,
+                        metadata: {
+                            taskId: state['taskId'],
+                            correlationId: state['correlationId'],
+                        },
                     });
                 }
                 catch (err) {
@@ -109,26 +134,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 thread；隔离时不写父 Checkpoint，避免短历史覆盖父对话
+                    replaceCheckpointMessages: !isolateContext,
                     userId,
                     delegationToken,
                     agentCode,
                     taskId: state['taskId'],
                     correlationId: state['correlationId'],
-                    sessionId: state['sessionId'],
+                    sessionId: isolateContext ? undefined : state['sessionId'],
+                    // ToolNode 用此标志在 interrupt 前拒绝 HITL
+                    skillIsolateContext: isolateContext || undefined,
                     executionContext: state['executionContext'],
                     loadedTools: scopedTools,
                     loadedSkills: state['loadedSkills'],
@@ -146,7 +177,7 @@ export class SubGraphCompiler {
                     hitlRespondedBy: state['hitlRespondedBy'],
                 };
                 const result = await adapter.runIsolatedLlmStreamFlags(() => adapter.invoke(subGraph, subGraphState));
-                // RT-6: 记录成功
+                // 进程内调试记录；生产记录是上面的 skill Span
                 await auditCtx?.finish({
                     status: 'success',
                     tokenUsage: result.tokenUsage,
@@ -182,19 +213,26 @@ 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;
                 return {
                     messages: outputMessages,
-                    currentNode: `subgraph:${dsl.name}`,
+                    currentNode: options?.parentNodeId
+                        || (dsl.name ? `subgraph:${dsl.name}` : 'subgraph'),
                     ...(nestedLastSpanId ? { lastSpanId: nestedLastSpanId } : {}),
                     ...(Array.isArray(perNode) && perNode.length > 0
                         ? {
@@ -211,18 +249,26 @@ export class SubGraphCompiler {
             }
             catch (err) {
                 const hitlPaused = unwrapHitlPaused(err);
-                if (hitlPaused) {
+                // 未隔离：HITL 暂停原样上抛。隔离：转 GRAPH_EXECUTION_ERROR，走 skill.failed，不当 waiting_hitl。
+                if (hitlPaused && !isolateContext) {
                     throw err;
                 }
+                const failErr = hitlPaused && isolateContext
+                    ? new AppError(ErrorCodes.GRAPH_EXECUTION_ERROR, SKILL_ISOLATE_HITL_MESSAGE, {
+                        exposeMessage: true,
+                        cause: err,
+                    })
+                    : 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) {
@@ -237,10 +283,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;
     /**

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

@@ -384,6 +384,8 @@ export class HitlHandler {
                 ...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({

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);
+}

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

@@ -0,0 +1,58 @@
+/**
+ * denoise — 降噪管线（design-v2 §6.3，M4）
+ *
+ * 数万 token 候选压成数百 token，LLM 只做判定与选择、绝不产出正文：
+ *   ① 近重去重（字符 n-gram Jaccard，纯函数，确定性优先）
+ *   ② 一次结构化 LLM 判定（主力模型，temp 0）→ DenoiseVerdict[]
+ *      { rawId, relevant, reason, keepSentences }——rawId 为复合键 sourceId:rawId
+ *      （rawId 仅源内唯一；payload 标签、verdict 匹配、filtered 项三处必须同用复合键，
+ *      裸 id 跨源碰撞会让两份文档共享同一 verdict：错滤另一源、按别家句子编号截正文）
+ *   ③ 代码按句子编号拼装原文（零改写：返回文本逐字出自原文句子）
+ *
+ * 防御策略（§6.5 误滤宁保守）：
+ *   verdict 调用或解析失败 / 文档缺 verdict 项 / keepSentences 无有效编号 → 整篇保留；
+ *   判定存活集为空 → react-loop 走 QUERY_REWRITE 重写兜底（本模块只报 verdictEmpty）。
+ */
+import type { ILLMProvider } from '../llm-node.js';
+import type { DenoiseVerdict, RagTokenUsage, RetrievalDoc } from './types.js';
+export declare const RAG_EMPTY_MARKER = "[rag] \u672A\u627E\u5230\u9AD8\u76F8\u5173\u7ED3\u679C";
+/** 格式化（降噪后的）文档集为最终上下文 */
+export declare function formatContext(query: string, docs: RetrievalDoc[]): string;
+export interface DenoiseInput {
+    query: string;
+    /** 融合后的候选文档集（可能数万 token） */
+    docs: RetrievalDoc[];
+    llmProvider: ILLMProvider;
+    /** 主力模型（与决策同款，不分档） */
+    model: string;
+    nodeId: string;
+    /** 近重判定阈值，缺省 0.8 */
+    nearDupThreshold?: number;
+    tokenUsage: RagTokenUsage[];
+}
+export interface DenoiseResult {
+    /** 存活文档（正文已按 keepSentences 截取） */
+    docs: RetrievalDoc[];
+    contextText: string;
+    /** 判定后存活集是否为空（react-loop 据此触发重写兜底） */
+    verdictEmpty: boolean;
+    /** 被滤文档与原因（空结果重写定向 / rag.denoise 事件用）；rawId 为复合键 sourceId:rawId（rewrite 归因整键匹配用） */
+    filtered: Array<{
+        rawId: string;
+        reason: string;
+    }>;
+}
+export declare function denoise(input: DenoiseInput): Promise<DenoiseResult>;
+export declare function rewriteQuery(input: {
+    query: string;
+    reasons: string[];
+    llmProvider: ILLMProvider;
+    model: string;
+    nodeId: string;
+    tokenUsage: RagTokenUsage[];
+}): Promise<string | undefined>;
+/** 确定性分句：按中英文句终符与换行切，句符随句保留（零改写：句子为原文子串） */
+export declare function splitSentences(content: string): string[];
+/** 解析判定输出：剥代码围栏、截取首尾方括号；解析失败返回 undefined（保守放行全部）。
+ *  rawId 不校验复合键形态——LLM 抄错（裸 id/截断）时 find 不中，该文档无 verdict 即整篇保留，仍走保守路径 */
+export declare function parseVerdicts(text: string): DenoiseVerdict[] | undefined;