@zhuan-ai/zhuanspec 2.17.8 → 2.17.11

package/dist/core/hooks/knowledge-references.d.ts

@@ -49,6 +49,14 @@ export interface KnowledgeReferencesFile {
 interface KnowledgeReferencesOptions {
     json?: boolean;
 }
+/**
+ * 判断是否为知识检索类工具调用（强特征、低误伤）。
+ *
+ * 覆盖：knowledge-agent-action / load-project-knowledge skill，以及前台 Bash 跑
+ * search_knowledge.py。这类工具出现时几乎必然处于 techDesign 流程，即便当前 phase
+ * 仍是 idle（set-phase 尚未执行、被检索抢跑），也应落盘，避免丢失知识溯源。
+ */
+export declare function isKnowledgeRetrievalTool(toolName: string, toolInput: Record<string, unknown>): boolean;
 export declare function selectKnowledgeReferenceToolResult(stdinData: Record<string, unknown>): {
     key: string;
     value: unknown;

package/dist/core/hooks/knowledge-references.js

@@ -143,6 +143,24 @@ function isKnowledgeAgentSearchInvocation(toolName, toolInput) {
     const skillName = extractSkillName(toolName, toolInput);
     return isKnowledgeSkill(skillName, toolName) || isKnowledgeCarrierSkill(skillName);
 }
+/**
+ * 判断是否为知识检索类工具调用（强特征、低误伤）。
+ *
+ * 覆盖：knowledge-agent-action / load-project-knowledge skill，以及前台 Bash 跑
+ * search_knowledge.py。这类工具出现时几乎必然处于 techDesign 流程，即便当前 phase
+ * 仍是 idle（set-phase 尚未执行、被检索抢跑），也应落盘，避免丢失知识溯源。
+ */
+export function isKnowledgeRetrievalTool(toolName, toolInput) {
+    if (isSkillAnalyticsTool(toolName))
+        return false;
+    if (isKnowledgeAgentSearchInvocation(toolName, toolInput))
+        return true;
+    if (toolName === 'Bash') {
+        const command = toolInput.command || '';
+        return isKnowledgeSearchScriptCommand(command);
+    }
+    return false;
+}
 function isGenericSuccessEnvelope(toolResult) {
     if (!isObject(toolResult))
         return false;
@@ -1499,13 +1517,25 @@ export async function knowledgeReferencesHook(_options) {
     };
     // 阶段过滤
     if (!ACTIVE_PHASES.includes(phase)) {
-        await appendDebugLog(debugBase, {
-            ...debugContext,
-            event: 'phase-skipped',
-            activePhases: ACTIVE_PHASES,
-        });
-        outputEnvelope();
-        return;
+        // 容错：techDesign 流程里知识检索可能抢跑在 set-phase 之前，此时 phase 仍是 idle。
+        // 对知识检索类工具（强特征、低误伤）放行，归到 tech-design 落盘，避免丢失知识溯源。
+        if (phase === 'idle' && isKnowledgeRetrievalTool(toolName, toolInput)) {
+            phase = 'tech-design';
+            await appendDebugLog(debugBase, {
+                ...debugContext,
+                event: 'idle-knowledge-retrieval-recovered',
+                recoveredPhase: phase,
+            });
+        }
+        else {
+            await appendDebugLog(debugBase, {
+                ...debugContext,
+                event: 'phase-skipped',
+                activePhases: ACTIVE_PHASES,
+            });
+            outputEnvelope();
+            return;
+        }
     }
     // TaskOutput 大输出会被截断并写入文件，读取全量文件以拿到完整知识 JSON。
     let effectiveToolResult = toolResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.17.8",
+  "version": "2.17.11",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -39,26 +39,6 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/zhuanspec.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/postinstall.js",
-    "check:pack-version": "node scripts/pack-version-check.mjs",
-    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
-    "release": "pnpm run release:ci",
-    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
-    "changeset": "changeset"
-  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -80,5 +60,23 @@
     "ora": "^8.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhuanspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
   }
-}
+}