@zhuan-ai/zhuanspec 2.17.6 → 2.17.8

package/dist/cli/hooks.js

@@ -16,6 +16,7 @@ import { deviationCheckHook } from '../core/hooks/deviation-check.js';
 import { recordProgressHook, initializeProgress } from '../core/hooks/record-progress.js';
 import { collectKnowledgeHook } from '../core/hooks/collect-knowledge.js';
 import { knowledgeUsageHook } from '../core/hooks/knowledge-usage.js';
+import { knowledgeReferencesHook } from '../core/hooks/knowledge-references.js';
 import { summarizeHook } from '../core/hooks/summarize.js';
 import { runUserInputHook } from '../core/hooks/user-input-hook.js';
 import { preArchiveHook } from '../core/hooks/pre-archive.js';
@@ -104,6 +105,14 @@ program
     .action(async (options) => {
     await knowledgeUsageHook(options);
 });
+// PostToolUse hook - knowledge references（知识溯源记录）
+program
+    .command('knowledge-references')
+    .description('PostToolUse hook - Record knowledge references during tech-design/proposal/apply')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .action(async (options) => {
+    await knowledgeReferencesHook(options);
+});
 // Stop hook
 program
     .command('summarize')

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

@@ -0,0 +1,91 @@
+/**
+ * Knowledge References Hook（知识溯源记录）
+ *
+ * PostToolUse 旁路 hook：在 tech-design / proposal / apply 三个阶段，
+ * 自动解析 Skill、Read/Grep/Glob、Bash、MCP 等工具的输出，
+ * 提取知识引用信息并落盘到 log/knowledge-references/{phase}.json。
+ *
+ * 设计原则：
+ *  - 纯旁路指标，始终 continue:true / 0 退出，绝不阻断主流程。
+ *  - 混合解析策略（C）：优先取结构化字段，fallback 启发式提取。
+ *  - refs 为空时不写入，避免噪音。
+ */
+export interface KnowledgeRef {
+    confidence?: number;
+    relevance?: string;
+    citedTitle?: string;
+    citedKnowledgeType?: string;
+    citedSource?: string;
+    citedUrl?: string;
+}
+export interface KnowledgeRecord {
+    source: string;
+    query: string;
+    at: string;
+    refs: KnowledgeRef[];
+}
+export interface KnowledgeAgentActionInvocation {
+    source: string;
+    skillName: string;
+    query: string;
+    at: string;
+    responseSource: string;
+    toolResultKey: string;
+    toolUseId?: string;
+    transcriptPath?: string;
+    changeId?: string;
+    request: Record<string, unknown>;
+    response: unknown;
+    launcherResponse?: unknown;
+    backgroundTaskId?: string;
+    nestedToolUseIds?: string[];
+    resolutionError?: string;
+}
+export interface KnowledgeReferencesFile {
+    phase: string;
+    records: KnowledgeRecord[];
+    knowledgeAgentActionInvocations?: KnowledgeAgentActionInvocation[];
+}
+interface KnowledgeReferencesOptions {
+    json?: boolean;
+}
+export declare function selectKnowledgeReferenceToolResult(stdinData: Record<string, unknown>): {
+    key: string;
+    value: unknown;
+};
+interface TaskOutputPayload {
+    outputFilePath?: string;
+    rawOutput?: string;
+}
+export declare function extractTaskOutputPayload(content: string): TaskOutputPayload;
+export declare function extractFirstJsonValueFromText(text: string): unknown;
+export declare function parseKnowledgeReferenceToolCall(toolName: string, toolInput: Record<string, unknown>, toolResult: unknown): KnowledgeRecord | null;
+export declare function buildKnowledgeAgentActionInvocation(toolName: string, toolInput: Record<string, unknown>, toolResult: unknown, context: {
+    toolResultKey: string;
+    toolUseId?: string;
+    transcriptPath?: string;
+    changeId?: string;
+}): KnowledgeAgentActionInvocation | null;
+/**
+ * 为 TaskOutput 命中的知识检索结果构造 invocation 记录，保留完整原始 JSON 到 response。
+ * 仅当解析出至少一条知识 ref 时返回，避免噪音。
+ */
+export declare function buildTaskOutputKnowledgeInvocation(toolInput: Record<string, unknown>, toolResult: unknown, context: {
+    toolResultKey: string;
+    toolUseId?: string;
+    transcriptPath?: string;
+    changeId?: string;
+}): KnowledgeAgentActionInvocation | null;
+/**
+ * 为前台 Bash 跑 search_knowledge.py 命中的知识检索结果构造 invocation 记录，
+ * 保留完整原始 JSON 到 response。仅当解析出至少一条知识 ref 时返回。
+ */
+export declare function buildBashKnowledgeInvocation(toolInput: Record<string, unknown>, toolResult: unknown, context: {
+    toolResultKey: string;
+    toolUseId?: string;
+    transcriptPath?: string;
+    changeId?: string;
+}): KnowledgeAgentActionInvocation | null;
+export declare function knowledgeReferencesHook(_options: KnowledgeReferencesOptions): Promise<void>;
+export {};
+//# sourceMappingURL=knowledge-references.d.ts.map