@zhuan-ai/zhuanspec 2.17.10 → 2.17.13

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/dist/core/init.js

@@ -1582,17 +1582,9 @@ export class InitCommand {
                             },
                         ],
                     },
-                    {
-                        matcher: 'Skill|Read|Grep|Glob|Bash|Agent|TaskOutput|mcp__.*',
-                        hooks: [
-                            {
-                                type: 'command',
-                                command: 'zhuanspec-hook knowledge-references --json',
-                                statusMessage: '📖 Recording knowledge references...',
-                                async: true,
-                            },
-                        ],
-                    },
+                    // knowledge-references hook 已下线：知识检索落盘改由 knowledge-agent-action
+                    // skill（search_knowledge.py / search_knowledge_no_code.py）在检索成功后直接完成，
+                    // 不再依赖 progress.json 的 phase 时序，避免重复记录。
                 ],
                 Stop: [
                     {

package/dist/core/templates/codex-hooks-template.js

@@ -65,12 +65,8 @@ const CODEX_DEFAULT_HOOKS = [
         matcher: 'Read|Grep|Glob|Bash',
         command: 'ZHUANSPEC_HOST=codex zhuanspec-hook knowledge-usage --json',
     },
-    {
-        event: 'PostToolUse',
-        matcher: 'Skill|Read|Grep|Glob|Bash|Agent|TaskOutput|mcp__.*',
-        command: 'ZHUANSPEC_HOST=codex zhuanspec-hook knowledge-references --json',
-        statusMessage: '📖 Recording knowledge references...',
-    },
+    // knowledge-references hook 已下线：知识检索落盘改由 knowledge-agent-action
+    // skill 在检索成功后直接完成，避免重复记录。
     {
         event: 'Stop',
         command: 'ZHUANSPEC_HOST=codex zhuanspec-hook summarize --json',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.17.10",
+  "version": "2.17.13",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",