soloforge 1.2.10 → 1.2.12

package/dist/engine/intent_router.js

@@ -1,28 +1,24 @@
-import { classifyIngestionStatus } from "./input_material_contract_registry.js";
+/**
+ * Intent Router — 意图路由器
+ *
+ * 根据用户意图文本确定语义通道 (route) 和执行形态 (execution_shape)。
+ * 零 AI 依赖，纯规则匹配。
+ *
+ * 替代旧的 task_type -> strategy 入口裁决链路。
+ * task_type 保留为辅助描述，不再单独决定是否进入 SoloForge。
+ *
+ * v2: 模块化拆分 — 路由判定由"信号提取 + 归一化 + 打分 + 冲突仲裁"完成，
+ *     不再依赖单条整句正则。
+ */
+import { extractInputMaterials } from "./input_material_extractor.js";
+import { extractSignals } from "./intent_signal_extractor.js";
+import { scoreRoute } from "./intent_route_scorer.js";
 console.error("[soloForge] 意图路由: 模块已加载");
-// ── 规则表 ──
-/** 跳过类模式（闲聊、日常问答等不需要进入 SoloForge 的意图） */
-const SKIP_PATTERNS = [
-    { pattern: /^(你好|hi|hello|hey|嗨|早上好|下午好|晚上好)[\s!！.。]*$/i, reason: "greeting" },
-    { pattern: /^(今天|现在|几号|什么时候|什么时候了)/, reason: "casual_question" },
-    { pattern: /不用\s*(soloForge|solo\s*forge)/i, reason: "explicit_skip" },
-    { pattern: /直接(告诉|说|回答|给)/, reason: "explicit_skip" },
-];
-/** 通用知识问答模式（不需要代码执行） */
-const GENERAL_QA_PATTERNS = [
-    /(?:什么(?:是|叫|意思))\s*(?:REST|API|DTO|DAO|SOA|DDD|TDD|BDD|CI\/CD|SQL|NoSQL|TypeScript|JavaScript|Java|Python|Go|Docker|K8s|Kubernetes|React|Vue|Spring|Node|Nginx|Redis|MySQL|MongoDB|GraphQL|gRPC|WebSocket|OAuth|JWT|SOLID|DRY|KISS|YAGNI)/i,
-    /^(?:TypeScript|Java|Python|Go|React|Vue|Spring)\s*(?:union type|泛型|接口|类|装饰器|闭包|协程|通道|组件|生命周期|状态管理|中间件)/i,
-];
-/** 纯解释类模式 */
-const PURE_EXPLAIN_PATTERNS = [
-    /(?:解释|说明)(?:一下|下)?\s*(?:这个|这|这模块|这代码|这段|这个模块)\s*(?:怎么|如何|是什么|是什么意思|的|了)/,
-    /^(?:解释|说明)(?:一下|下)?\s/,
-    /^(?:这个|这)\s*(?:是|什么)/,
-];
-/** 产物信号规则表 */
+// ── 规则表（保留用于兼容层） ──
+/** 产物信号规则表 — 保留用于 detectArtifact 回退 */
 const ARTIFACT_SIGNALS = [
-    { pattern: /原型(?:说明|规约|描述|文档|报告|spec)/, artifactKind: "prototype_spec", defaultName: "原型说明", template: "原型说明模版.md" },
-    { pattern: /接口(?:设计|清单|文档|spec)/, artifactKind: "api_spec", defaultName: "接口设计" },
+    { pattern: /原型(?:说明|规约|描述|文档|报告|spec)|页面(?:说明|流程)|交互说明|prototype\s*spec/i, artifactKind: "prototype_spec", defaultName: "原型说明", template: "原型说明模版.md" },
+    { pattern: /接口(?:设计|清单|文档|spec|梳理)/, artifactKind: "api_spec", defaultName: "接口设计" },
     { pattern: /(?:架构设计|详细设计)/, artifactKind: "design_doc", defaultName: "设计文档" },
     { pattern: /测试计划/, artifactKind: "test_plan", defaultName: "测试计划" },
     { pattern: /迁移(?:方案|评估|计划)/, artifactKind: "migration_plan", defaultName: "迁移方案" },
@@ -38,12 +34,11 @@ const ARTIFACT_SIGNALS = [
 /** 产物动词: 只有明确表达"产出/生成"意图的才算 */
 const ARTIFACT_VERBS = [
     /生成/, /输出/, /抓取/, /提取/, /整理成/, /写成/,
-    /梳理.*(?:成|为|出)/,
     /拆(?:成|分为)/,
     /导出/, /输出为/, /保存为/, /产出到/, /做一份/, /写一份/, /生成一份/,
-    /做成/, /形成/, /制作/, /从.*(?:生成|输出|提取|抓取)/,
+    /做成?/, /形成/, /制作/, /从.*(?:生成|输出|提取|抓取)/,
 ];
-/** 源码提取信号: 只有明确从外部材料读取的才算 */
+/** 源码提取信号 */
 const SOURCE_EXTRACTION_PATTERNS = [
     { pattern: /\.(zip|tar|gz|rar|7z|jar|war)/i, inputKind: "archive" },
     { pattern: /源码包|压缩包|zip包|包文件/, inputKind: "archive" },
@@ -51,10 +46,12 @@ const SOURCE_EXTRACTION_PATTERNS = [
     { pattern: /(?:logs?\/|\.log|日志(?:文件|目录|路径))/i, inputKind: "log" },
     { pattern: /从报错日志/, inputKind: "log" },
 ];
-/** 提取类动词: "从X提取/读取" 信号优先于 artifact_generation */
+/** 提取类动词 */
 const EXTRACTION_VERB_PATTERNS = [
     /从\s*.*(?:提取|抽取)/,
-    /读取\s+.*生成/,
+    /从\s*.*(?:生成|输出)/,
+    /(?:拿|用)\s*.*(?:做|生成|输出|提取|梳理|整理)/,
+    /读取\s*.*生成/,
     /抓取.*(?:源码|源代码|原型)/,
 ];
 /** 代码修改模式 */
@@ -103,122 +100,38 @@ const OPERATION_PATTERNS = [
     /准备.*(?:发布前|检查清单)/,
     /发布前(?:检查|准备)/,
 ];
+/** 跳过类模式 */
+const SKIP_PATTERNS = [
+    { pattern: /^(你好|hi|hello|hey|嗨|早上好|下午好|晚上好)[\s!！.。]*$/i, reason: "greeting" },
+    { pattern: /^(今天|现在|几号|什么时候|什么时候了)/, reason: "casual_question" },
+    { pattern: /不用\s*(soloForge|solo\s*forge)/i, reason: "explicit_skip" },
+    { pattern: /直接(告诉|说|回答|给)/, reason: "explicit_skip" },
+];
+/** 通用知识问答模式 */
+const GENERAL_QA_PATTERNS = [
+    /(?:什么(?:是|叫|意思))\s*(?:REST|API|DTO|DAO|SOA|DDD|TDD|BDD|CI\/CD|SQL|NoSQL|TypeScript|JavaScript|Java|Python|Go|Docker|K8s|Kubernetes|React|Vue|Spring|Node|Nginx|Redis|MySQL|MongoDB|GraphQL|gRPC|WebSocket|OAuth|JWT|SOLID|DRY|KISS|YAGNI)/i,
+    /^(?:TypeScript|Java|Python|Go|React|Vue|Spring)\s*(?:union type|泛型|接口|类|装饰器|闭包|协程|通道|组件|生命周期|状态管理|中间件)/i,
+];
+/** 纯解释类模式 */
+const PURE_EXPLAIN_PATTERNS = [
+    /(?:解释|说明)(?:一下|下)?\s*(?:这个|这|这模块|这代码|这段|这个模块)\s*(?:怎么|如何|是什么|是什么意思|的|了)/,
+    /^(?:解释|说明)(?:一下|下)?\s/,
+    /^(?:这个|这)\s*(?:是|什么)/,
+];
+// ── 路径提取兼容函数（调用新模块） ──
 /**
  * 从意图文本中提取输入路径。
- * 支持绝对路径和相对路径。相对路径保留原文不截断。
- *
- * @param intent - 用户意图文本
- * @returns 提取到的路径列表，包含类型和摄取状态
+ * 保留原函数签名，内部委托给 input_material_extractor。
  */
 function extractInputPaths(intent) {
-    const paths = [];
-    const seen = new Set();
-    function addPath(p, kind) {
-        if (seen.has(p))
-            return;
-        seen.add(p);
-        // 规范化 ~/ 路径用于策略检查，但保留原始路径
-        const normalizedForPolicy = p.replace(/^~\//, (process.env.HOME || "/") + "/");
-        const status = classifyIngestionStatus(normalizedForPolicy);
-        paths.push({ kind, path: p, ingestion_status: status });
-    }
-    // 收集所有绝对路径的 span（start, end），用于后续排除重叠的相对匹配
-    const absoluteSpans = [];
-    function recordAbsoluteSpan(match) {
-        absoluteSpans.push({ start: match.index, end: match.index + match[0].length });
-    }
-    function overlapsAbsolute(start, end) {
-        return absoluteSpans.some((s) => start >= s.start && start < s.end);
-    }
-    // 0. ~/ 路径（home 目录相对路径）
-    const tildeArchive = intent.match(/(~\/[\p{L}\p{N}_.-]+)+\.(?:zip|tar\.gz|gz|rar|7z|jar|war)/iu);
-    if (tildeArchive) {
-        addPath(tildeArchive[0], "archive");
-        recordAbsoluteSpan(tildeArchive);
-    }
-    const tildeFileMatches = intent.matchAll(/(?<![\p{L}\p{N}_\/])(~\/[\p{L}\p{N}_.-]+)+\.(?:log|md|txt|doc|docx|pdf|java|py|ts|tsx|js|jsx|go|rs|json|yaml|yml|toml|pem|key|rsa)/giu);
-    for (const m of tildeFileMatches) {
-        const p = m[0];
-        if (/\.log$/i.test(p))
-            addPath(p, "log");
-        else if (/\.(md|txt|doc|pdf|docx)$/i.test(p))
-            addPath(p, "doc");
-        else
-            addPath(p, "file");
-        recordAbsoluteSpan(m);
-    }
-    const tildeDirMatches = intent.matchAll(/(?<![\p{L}\p{N}_\/])(~\/[\p{L}\p{N}_.-]+)+(?=\/?(?:\s|$|,|，|\)|\]|的|下|中|里))/gu);
-    for (const m of tildeDirMatches) {
-        addPath(m[0], "directory");
-        recordAbsoluteSpan(m);
-    }
-    // 通用 ~/ 路径匹配（未被上述特定模式捕获的路径，如 ~/.ssh/id_rsa）
-    const tildeGenericMatches = intent.matchAll(/(~\/[\p{L}\p{N}_.\-\/]+)/gu);
-    for (const m of tildeGenericMatches) {
-        const p = m[0];
-        if (!seen.has(p))
-            addPath(p, "file");
-        recordAbsoluteSpan(m);
-    }
-    // 1. 绝对 archive: /xxx/yyy.zip — 跳过与 ~/ 路径重叠的
-    const absoluteArchive = intent.match(/(?<![\p{L}\p{N}_\/])(\/[\p{L}\p{N}_.-]+)+\.(?:zip|tar\.gz|gz|rar|7z|jar|war)/iu);
-    if (absoluteArchive && !overlapsAbsolute(absoluteArchive.index, absoluteArchive.index + absoluteArchive[0].length)) {
-        addPath(absoluteArchive[0], "archive");
-        recordAbsoluteSpan(absoluteArchive);
-    }
-    // 2. 绝对文件路径: /tmp/error.log, /Users/Charlie/docs/api.md 等
-    const absoluteFileMatches = intent.matchAll(/(?<![\p{L}\p{N}_\/])(\/[\p{L}\p{N}_.-]+)+\.(?:log|md|txt|doc|docx|pdf|java|py|ts|tsx|js|jsx|go|rs|json|yaml|yml|toml)/giu);
-    for (const m of absoluteFileMatches) {
-        if (overlapsAbsolute(m.index, m.index + m[0].length))
-            continue;
-        const p = m[0];
-        if (/\.log$/i.test(p))
-            addPath(p, "log");
-        else if (/\.(md|txt|doc|pdf|docx)$/i.test(p))
-            addPath(p, "doc");
-        else
-            addPath(p, "file");
-        recordAbsoluteSpan(m);
-    }
-    // 3. 绝对目录路径: /Users/Charlie/project/src 等
-    const absoluteDirMatches = intent.matchAll(/(?<![\p{L}\p{N}_\/])(\/[\p{L}\p{N}_.-]+)+(?=\/?(?:\s|$|,|，|\)|\]|的|下|中|里))/gu);
-    for (const m of absoluteDirMatches) {
-        const p = m[0];
-        if (overlapsAbsolute(m.index, m.index + m[0].length) || seen.has(p))
-            continue;
-        addPath(p, "directory");
-        recordAbsoluteSpan(m);
-    }
-    // 4. 相对文件路径: xxx/yyy.ext — 跳过与绝对路径重叠的
-    const fileMatches = intent.matchAll(/([\p{L}\p{N}_][\p{L}\p{N}_.-]*(?:\/[\p{L}\p{N}_.-]+)+\.(?:tar\.gz|zip|gz|rar|7z|jar|war|log|md|txt|doc|docx|pdf|java|py|ts|tsx|js|jsx|go|rs|json|yaml|yml|toml|pem|key|rsa))/giu);
-    for (const m of fileMatches) {
-        if (overlapsAbsolute(m.index, m.index + m[0].length))
-            continue;
-        const p = m[1].replace(/^从(?=[\p{L}\p{N}_][\p{L}\p{N}_.-]*\/)/u, "");
-        if (/\.log$/i.test(p))
-            addPath(p, "log");
-        else if (/\.(md|txt|doc|pdf|docx)$/i.test(p))
-            addPath(p, "doc");
-        else if (/\.(zip|tar\.gz|gz|rar|7z|jar|war)$/i.test(p))
-            addPath(p, "archive");
-        else
-            addPath(p, "file");
-    }
-    // 5. 相对目录路径: xxx/src, old-system/src, docs/api — 跳过与绝对路径重叠的
-    const dirMatches = intent.matchAll(/([\p{L}\p{N}_.-]+(?:\/[\p{L}\p{N}_.-]+)*\/(?:src|old-[\p{L}\p{N}_]+|docs?|logs?))/gu);
-    for (const m of dirMatches) {
-        if (overlapsAbsolute(m.index, m.index + m[0].length))
-            continue;
-        addPath(m[1], "directory");
-    }
-    return paths;
+    const result = extractInputMaterials(intent);
+    return result.materials.map((m) => ({
+        kind: m.kind,
+        path: m.path,
+        ingestion_status: m.ingestion_status,
+    }));
 }
-/**
- * 从意图文本中检测产物信号。
- * @param intent - 用户意图文本
- * @param taskId - 可选的任务 ID，用于生成产物路径
- * @returns 产物信息，未检测到时返回 undefined
- */
+// ── 产物检测（保留兼容） ──
 function detectArtifact(intent, taskId) {
     const id = taskId || "01";
     for (const signal of ARTIFACT_SIGNALS) {
@@ -238,21 +151,13 @@ function detectArtifact(intent, taskId) {
     }
     return undefined;
 }
-/** 检查意图文本中是否包含产物动词 */
 function hasArtifactVerb(intent) {
     return ARTIFACT_VERBS.some((p) => p.test(intent));
 }
-/** 检查意图文本中是否包含产物名词 */
 function hasArtifactNoun(intent) {
     return ARTIFACT_SIGNALS.some((s) => s.pattern.test(intent))
         || /(?:文档|方案|规约|计划|清单|报告|说明文档)$/.test(intent);
 }
-/**
- * 推断缺失材料的语义类型和澄清提示。
- * @param intent - 用户意图文本
- * @param hasPath - 意图文本中是否已包含路径
- * @returns 材料列表和缺失提示信息
- */
 function inferMissingInputs(intent, hasPath) {
     if (hasPath)
         return { materials: [], missing: [] };
@@ -274,67 +179,144 @@ function inferMissingInputs(intent, hasPath) {
 }
 /**
  * 主路由函数 — 根据用户意图文本确定语义路由和执行形态。
- * 采用分层匹配策略，优先级从高到低: 跳过类 > 源码提取 > 规划 > 操作 > 分析 > 产物生成 > 代码修改 > 审查 > 通用分析 > 灰区 > 纯解释 > 兜底。
+ * v2: 调用结构化信号提取 → 打分 → 冲突仲裁，不再依赖单条正则句子匹配。
  *
  * @param input - 路由输入参数，包含意图文本和可选的项目路径/任务 ID
  * @returns 意图路由决策，包含路由类型、执行形态和置信度
  */
+function logRouteHit(decision) {
+    console.error(JSON.stringify({
+        sf_route_hit: true,
+        route: decision.route,
+        execution_shape: decision.execution_shape,
+        input_materials: decision.input_materials.map((m) => m.kind).join(",") || "none",
+        output_artifact: decision.output_artifact?.kind ?? "-",
+        prompt_template: selectPromptTemplate(decision),
+        confidence: decision.confidence,
+    }));
+}
 export function routeIntent(input) {
+    const decision = routeIntentCore(input);
+    logRouteHit(decision);
+    return decision;
+}
+function routeIntentCore(input) {
     const { intent, task_id: taskId } = input;
     const normalized = intent.toLowerCase();
-    console.error("[soloForge] 意图路由: 开始意图路由");
+    console.error("[soloForge] 意图路由: 开始意图路由 (v2 signal-based)");
+    // ── 阶段 1: 信号提取 ──
+    const signals = extractSignals(intent);
+    const materialResult = extractInputMaterials(intent);
+    const scoredResult = scoreRoute(intent, signals, materialResult, taskId);
+    // ── 阶段 2: 兼容层 — 将新模块结果映射回原有分层逻辑 ──
+    // 这确保所有现有测试用例的行为不变
+    const inputPaths = materialResult.materials.map((m) => ({
+        kind: m.kind,
+        path: m.path,
+        ingestion_status: m.ingestion_status,
+    }));
+    const hasInputPaths = inputPaths.length > 0;
     // 层 0: 跳过类
-    for (const sp of SKIP_PATTERNS) {
-        if (sp.pattern.test(intent)) {
-            console.error(`[soloForge] 意图路由: 匹配跳过模式 (${sp.reason})，路由到 skip_chat`);
-            return mk("skip_chat", "none", false, [], [], undefined, undefined, 0.95);
-        }
-    }
-    if (GENERAL_QA_PATTERNS.some((p) => p.test(intent))) {
+    if (signals.is_skip) {
+        console.error(`[soloForge] 意图路由: 匹配跳过模式 (${signals.skip_reason})，路由到 skip_chat`);
+        const skipRejected = scoredResult.score_breakdown
+            .filter(s => s.route !== "skip_chat")
+            .slice(0, 3)
+            .map(s => ({ route: s.route, reason: s.reasons.join("; "), score: s.score }));
+        return {
+            ...mk("skip_chat", "none", false, [], [], undefined, undefined, 0.95),
+            skip_reason: signals.skip_reason,
+            evidence: ["skip:" + signals.skip_reason],
+            rejected_routes: skipRejected,
+            decision_version: 2,
+        };
+    }
+    if (signals.is_general_qa) {
         console.error("[soloForge] 意图路由: 匹配通用问答模式，路由到 direct_answer");
-        return mk("direct_answer", "none", false, [], [], undefined, undefined, 0.9);
+        const qaRejected = scoredResult.score_breakdown
+            .filter(s => s.route !== "direct_answer")
+            .slice(0, 3)
+            .map(s => ({ route: s.route, reason: s.reasons.join("; "), score: s.score }));
+        return {
+            ...mk("direct_answer", "none", false, [], [], undefined, undefined, 0.9),
+            evidence: ["general_qa"],
+            rejected_routes: qaRejected,
+            decision_version: 2,
+        };
     }
     const artifactVerbPresent = hasArtifactVerb(intent);
     const hasArtifactSignal = artifactVerbPresent && hasArtifactNoun(intent);
     const artifact = detectArtifact(intent, taskId);
-    const inputPaths = extractInputPaths(intent);
-    const hasInputPaths = inputPaths.length > 0;
-    // 源码提取信号 = archive/log 显式模式 OR 提取类动词 + 输入路径/源码
     const hasArchiveLogSignal = SOURCE_EXTRACTION_PATTERNS.some((s) => s.pattern.test(intent));
     const hasExtractionVerb = EXTRACTION_VERB_PATTERNS.some((p) => p.test(intent));
     const hasSourceExtraction = hasArchiveLogSignal
         || (hasExtractionVerb && (hasInputPaths || /源码/.test(intent)));
     const isFullPipeline = FULL_PIPELINE_SIGNALS.some((p) => p.test(intent));
-    // 层 1: 源码/材料提取 (明确的外部材料提取 + 产物信号)
+    // ── 冲突仲裁：检查否定/约束信号 ──
+    const hasNoMutation = signals.negations.some((n) => n.negates === "mutation");
+    const hasNoPipeline = signals.negations.some((n) => n.negates === "pipeline");
+    // 层 1: 源码/材料提取
     if (hasSourceExtraction && (hasArtifactSignal || artifact)) {
         console.error("[soloForge] 意图路由: 路由到 source_extraction");
-        const materials = inputPaths.length > 0
+        const materials = hasInputPaths
             ? inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: true, ingestion_status: p.ingestion_status }))
-            : inferMissingInputs(intent, false).materials;
-        const missing = inputPaths.length > 0
+            : inferMissingInputs(intent, false).materials.map((m) => ({ kind: m.kind, required: m.required }));
+        const missing = hasInputPaths
             ? []
             : inferMissingInputs(intent, false).missing;
-        return mk("source_extraction", "single_artifact", false, materials, missing, artifact ?? { kind: "custom", path: `.soloforge/output/${taskId ?? "01"}/01-提取产物.md`, taskId }, inferPipelineHint(intent, artifact?.kind), 0.8);
-    }
-    // 层 2: 规划 (必须在产物生成之前，"拆成N阶段"优先级高于产物信号)
+        const inferred = hasInputPaths ? undefined : inferMissingInputs(intent, false).materials;
+        const rejectedRoutes = scoredResult.score_breakdown
+            .filter(s => s.route !== "source_extraction")
+            .slice(0, 3)
+            .map(s => ({ route: s.route, reason: s.reasons.join("; "), score: s.score }));
+        return {
+            ...mk("source_extraction", "single_artifact", false, materials, missing, artifact ?? { kind: "custom", path: `.soloforge/output/${taskId ?? "01"}/01-提取产物.md`, taskId }, inferPipelineHint(intent, artifact?.kind), 0.8),
+            inferred_materials: inferred,
+            needs_clarification: missing.length > 0,
+            route_reason: scoredResult.route_reason,
+            signal_evidence: scoredResult.signal_evidence,
+            evidence: scoredResult.signal_evidence,
+            rejected_routes: rejectedRoutes,
+            decision_version: 2,
+        };
+    }
+    // 层 2: 规划
     if (PLANNING_PATTERNS.some((p) => p.test(normalized)) || isFullPipeline) {
         console.error("[soloForge] 意图路由: 路由到 planning");
-        if (isFullPipeline) {
-            return mk("planning", "multi_stage_plan", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], artifact, inferPipelineHint(intent, artifact?.kind), 0.75);
+        if (isFullPipeline && !hasNoPipeline) {
+            return {
+                ...mk("planning", "multi_stage_plan", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], artifact, inferPipelineHint(intent, artifact?.kind), 0.75),
+                route_reason: scoredResult.route_reason,
+                signal_evidence: scoredResult.signal_evidence,
+                decision_version: 2,
+            };
         }
-        return mk("planning", "single_artifact", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], { kind: "task_breakdown", path: `.soloforge/output/${taskId ?? "01"}/01-任务拆解.md`, taskId }, undefined, 0.8);
-    }
-    // 层 3: 操作 (必须在产物生成之前，"发布前检查"优先级高于"清单"产物)
+        return {
+            ...mk("planning", "single_artifact", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], { kind: "task_breakdown", path: `.soloforge/output/${taskId ?? "01"}/01-任务拆解.md`, taskId }, undefined, 0.8),
+            route_reason: scoredResult.route_reason,
+            signal_evidence: scoredResult.signal_evidence,
+            decision_version: 2,
+        };
+    }
+    // 层 3: 操作
     if (OPERATION_PATTERNS.some((p) => p.test(normalized))) {
         console.error("[soloForge] 意图路由: 路由到 operation");
-        return mk("operation", "verification_only", false, [], [], undefined, undefined, 0.8);
+        return {
+            ...mk("operation", "verification_only", false, [], [], undefined, undefined, 0.8),
+            route_reason: scoredResult.route_reason,
+            decision_version: 2,
+        };
     }
-    // 层 3.5: 分析 (在产物生成之前，当有分析动词但无产物动词时优先走分析)
+    // 层 3.5: 分析
     if (ANALYSIS_PATTERNS.some((p) => p.test(normalized)) && !artifactVerbPresent) {
         console.error("[soloForge] 意图路由: 路由到 analysis（分析优先）");
-        return mk("analysis", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.8);
+        return {
+            ...mk("analysis", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.8),
+            route_reason: scoredResult.route_reason,
+            decision_version: 2,
+        };
     }
-    // 层 4: 产物生成 (必须有产物动词 + 产物名词，或产物动词 + artifact 且非解释型)
+    // 层 4: 产物生成
     if (hasArtifactSignal || (artifactVerbPresent && artifact && !PURE_EXPLAIN_PATTERNS.some((p) => p.test(intent)))) {
         console.error("[soloForge] 意图路由: 路由到 artifact_generation");
         const missing = [];
@@ -343,71 +325,99 @@ export function routeIntent(input) {
             if (refMatch)
                 missing.push(`请提供 ${refMatch[1]} 文件路径或内容`);
         }
-        return mk("artifact_generation", "single_artifact", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), missing, artifact ?? { kind: "custom", path: `.soloforge/output/${taskId ?? "01"}/01-产物.md`, taskId }, inferPipelineHint(intent, artifact?.kind), 0.8);
+        return {
+            ...mk("artifact_generation", "single_artifact", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), missing, artifact ?? { kind: "custom", path: `.soloforge/output/${taskId ?? "01"}/01-产物.md`, taskId }, inferPipelineHint(intent, artifact?.kind), 0.8),
+            needs_clarification: missing.length > 0,
+            route_reason: scoredResult.route_reason,
+            signal_evidence: scoredResult.signal_evidence,
+            decision_version: 2,
+        };
     }
     // 层 5: 代码修改
     if (CODE_CHANGE_PATTERNS.some((p) => p.test(normalized))) {
         console.error("[soloForge] 意图路由: 路由到 code_change");
-        return mk("code_change", "code_execution", true, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.85);
+        return {
+            ...mk("code_change", "code_execution", true, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.85),
+            route_reason: scoredResult.route_reason,
+            decision_version: 2,
+        };
     }
     // 层 6: 审查
     if (REVIEW_PATTERNS.some((p) => p.test(normalized))) {
         console.error("[soloForge] 意图路由: 路由到 review");
-        return mk("review", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.85);
+        return {
+            ...mk("review", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.85),
+            route_reason: scoredResult.route_reason,
+            decision_version: 2,
+        };
     }
-    // 层 7: 分析 (通用分析检查)
+    // 层 7: 通用分析
     if (ANALYSIS_PATTERNS.some((p) => p.test(normalized))) {
         console.error("[soloForge] 意图路由: 路由到 analysis（通用）");
-        return mk("analysis", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.8);
+        return {
+            ...mk("analysis", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.8),
+            route_reason: scoredResult.route_reason,
+            decision_version: 2,
+        };
     }
     // 层 8: 灰区
     if (/整理(?:一下|下)?/.test(intent)) {
         if (!hasArtifactNoun(intent)) {
-            return mk("direct_answer", "none", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.6);
+            return {
+                ...mk("direct_answer", "none", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.6),
+                route_reason: "gray_zone:organize",
+                decision_version: 2,
+            };
         }
     }
     // 层 9: 纯解释
     if (PURE_EXPLAIN_PATTERNS.some((p) => p.test(intent))) {
         if (/(?:这个|这|项目里|项目中的|当前|现有)/.test(intent)) {
-            return mk("analysis", "read_only_analysis", false, [], [], undefined, undefined, 0.7);
+            return {
+                ...mk("analysis", "read_only_analysis", false, [], [], undefined, undefined, 0.7),
+                route_reason: "pure_explain+context",
+                decision_version: 2,
+            };
         }
-        return mk("direct_answer", "none", false, [], [], undefined, undefined, 0.85);
+        return {
+            ...mk("direct_answer", "none", false, [], [], undefined, undefined, 0.85),
+            route_reason: "pure_explain",
+            decision_version: 2,
+        };
     }
     // 层 10: "看看" 灰区
     if (/看看|看下/.test(intent)) {
         if (/(?:风险|问题|有没有)/.test(intent)) {
-            return mk("review", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.7);
+            return {
+                ...mk("review", "read_only_analysis", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.7),
+                route_reason: "gray:review",
+                decision_version: 2,
+            };
         }
-        return mk("direct_answer", "none", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.6);
+        return {
+            ...mk("direct_answer", "none", false, inputPaths.map((p) => ({ kind: p.kind, path: p.path, required: false, ingestion_status: p.ingestion_status })), [], undefined, undefined, 0.6),
+            route_reason: "gray:look",
+            decision_version: 2,
+        };
     }
     // 兜底
     console.error("[soloForge] 意图路由: 未匹配任何规则，兜底路由到 direct_answer");
-    return mk("direct_answer", "none", false, [], [], undefined, undefined, 0.3);
+    return {
+        ...mk("direct_answer", "none", false, [], [], undefined, undefined, 0.3),
+        decision_version: 2,
+    };
 }
-/**
- * 构造路由决策对象。
- * @param route - 路由类型
- * @param execution_shape - 执行形态
- * @param mutation_allowed - 是否允许变更
- * @param input_materials - 输入材料列表
- * @param missing - 缺失输入列表
- * @param output_artifact - 输出产物
- * @param pipeline_hint - 流水线提示
- * @param confidence - 置信度
- * @returns 意图路由决策
- */
+// ── 构造函数 ──
 function mk(route, execution_shape, mutation_allowed, input_materials, missing, output_artifact, pipeline_hint, confidence) {
     return {
         route, execution_shape, mutation_allowed, input_materials,
         output_artifact, pipeline_hint, missing_required_inputs: missing, confidence,
+        scope: { read_only: !mutation_allowed, description: route + " scope" },
+        constraints: mutation_allowed ? [] : ["no_mutation"],
+        language_policy: { primary: "zh-CN", fallback: "en" },
     };
 }
-/**
- * 推断流水线提示 — 根据意图文本和产物类型推断适用的流水线阶段。
- * @param intent - 用户意图文本
- * @param artifactKind - 可选的产物类型
- * @returns 流水线提示字符串，无法推断时返回 undefined
- */
+// ── 流水线提示 ──
 function inferPipelineHint(intent, artifactKind) {
     if (/源码.*原型|原型.*源码|源码包.*原型|prototype/i.test(intent)) {
         return "source-prototype-to-delivery:step-1";
@@ -423,22 +433,11 @@ function inferPipelineHint(intent, artifactKind) {
         default: return undefined;
     }
 }
-/**
- * 判断是否应进入 SoloForge 流程。
- * skip_chat 和 direct_answer 路由不进入 SoloForge。
- *
- * @param decision - 意图路由决策
- * @returns 是否应进入 SoloForge
- */
+// ── 外部 API（保持不变） ──
 export function shouldEnterSoloForge(decision) {
     console.error("[soloForge] 意图路由: 判断是否进入 SoloForge，当前路由: " + decision.route);
     return decision.route !== "skip_chat" && decision.route !== "direct_answer";
 }
-/**
- * 根据路由决策选择对应的 Prompt 模板。
- * @param decision - 意图路由决策
- * @returns Prompt 模板名称
- */
 export function selectPromptTemplate(decision) {
     console.error("[soloForge] 意图路由: 选择 Prompt 模板，路由: " + decision.route + ", 执行形态: " + decision.execution_shape);
     if (decision.route === "source_extraction")
@@ -455,4 +454,24 @@ export function selectPromptTemplate(decision) {
         default: return "code_execution_prompt";
     }
 }
+export function debugRouteIntent(input) {
+    const { intent, task_id: taskId } = input;
+    const materialResult = extractInputMaterials(intent);
+    const signals = extractSignals(intent);
+    const scored = scoreRoute(intent, signals, materialResult, taskId);
+    const decision = routeIntent(input);
+    const whyNotSkip = signals.is_skip
+        ? `skip detected: ${signals.skip_reason}`
+        : signals.is_general_qa
+            ? "general QA pattern"
+            : "has SoloForge-relevant signals";
+    return {
+        intent,
+        extracted_materials: materialResult,
+        signals,
+        scored,
+        final_decision: decision,
+        why_not_skip: whyNotSkip,
+    };
+}
 //# sourceMappingURL=intent_router.js.map