@zhuan-ai/zhuanspec 2.17.0 → 2.17.1

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

@@ -14,6 +14,7 @@ interface UsageCounter {
     refCount: number;
     lastRefAt: string;
 }
+type ProjectWikiRefSource = 'file' | 'llmwiki' | string;
 /** usage.json 落点结构：zhuanspec/knowledge/.metrics/usage.json */
 export interface KnowledgeUsageStats {
     schemaVersion: 1;
@@ -26,6 +27,10 @@ export interface KnowledgeUsageStats {
     byFile: Record<string, UsageCounter>;
     /** 键 = 相对 ZhuanSpec 根的 ProjectWiki 路径，如 service/.project-wiki/project.md */
     byProjectWikiFile: Record<string, UsageCounter>;
+    /** 键 = ProjectWiki 引用来源，如 file / llmwiki */
+    projectWikiRefsBySource: Record<string, UsageCounter>;
+    /** 键 = ProjectWiki 文件路径，值 = 该文件按来源拆分的引用计数 */
+    byProjectWikiFileSource: Record<string, Record<string, UsageCounter>>;
     lastUpdatedAt: string;
 }
 /** 单次上报输入（清晰可复用的上报接口契约） */
@@ -35,6 +40,22 @@ export interface KnowledgeRefEvent {
     /** 引用时间，缺省取 getBeijingTime() */
     refAt?: string;
 }
+export interface ProjectWikiEffectiveRef {
+    /** llmwiki 返回的 ProjectWiki 文档路径，支持绝对路径或相对 ZhuanSpec 根路径 */
+    path: string;
+    /** llmwiki 召回分数，仅用于后续分析，不参与是否计数的判定 */
+    score?: number;
+    /** 调用方判定该文档为有效引用的简要原因 */
+    reason?: string;
+}
+export interface ProjectWikiRefEvent {
+    source?: ProjectWikiRefSource;
+    query?: string;
+    project?: string;
+    effectiveRefs: ProjectWikiEffectiveRef[];
+    /** 引用时间，缺省取 getBeijingTime() */
+    refAt?: string;
+}
 interface KnowledgeUsageOptions {
     json?: boolean;
     file?: string;
@@ -43,6 +64,14 @@ interface KnowledgeUsageOptions {
 export declare function getUsagePath(knowledgeDir: string): string;
 /** 读取 usage.json，缺失/损坏均返回空结构（容错，不抛） */
 export declare function readUsageStats(knowledgeDir: string): Promise<KnowledgeUsageStats>;
+export declare function extractLlmwikiEffectiveRefsFromHookInput(stdinData: Record<string, unknown>): ProjectWikiEffectiveRef[];
+/**
+ * 上报 llmwiki 召回后被实际使用的 ProjectWiki 文档。
+ * 只统计调用方传入的 effectiveRefs，不统计全部召回结果；同一次事件内同一路径去重。
+ *
+ * @returns 实际累加的唯一文档数
+ */
+export declare function reportProjectWikiRefs(knowledgeDir: string, event: ProjectWikiRefEvent): Promise<number>;
 /**
  * 清晰可复用的上报接口：累加一次引用。
  *  - filePath 未命中 knowledge/ 三类目录 → no-op 返回 false。

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

@@ -28,6 +28,8 @@ function emptyUsage() {
         byId: {},
         byFile: {},
         byProjectWikiFile: {},
+        projectWikiRefsBySource: {},
+        byProjectWikiFileSource: {},
         lastUpdatedAt: '',
     };
 }
@@ -48,6 +50,12 @@ export async function readUsageStats(knowledgeDir) {
             byProjectWikiFile: parsed.byProjectWikiFile && typeof parsed.byProjectWikiFile === 'object'
                 ? parsed.byProjectWikiFile
                 : {},
+            projectWikiRefsBySource: parsed.projectWikiRefsBySource && typeof parsed.projectWikiRefsBySource === 'object'
+                ? parsed.projectWikiRefsBySource
+                : {},
+            byProjectWikiFileSource: parsed.byProjectWikiFileSource && typeof parsed.byProjectWikiFileSource === 'object'
+                ? parsed.byProjectWikiFileSource
+                : {},
             lastUpdatedAt: typeof parsed.lastUpdatedAt === 'string' ? parsed.lastUpdatedAt : '',
         };
     }
@@ -95,6 +103,143 @@ function matchProjectWikiFile(repoRoot, filePath) {
         return null;
     return segments.join('/');
 }
+function normalizeProjectWikiFile(repoRoot, filePath) {
+    if (!filePath)
+        return null;
+    if (path.isAbsolute(filePath)) {
+        return matchProjectWikiFile(repoRoot, filePath);
+    }
+    return matchProjectWikiFile(repoRoot, path.join(repoRoot, filePath));
+}
+function bump(counter, refAt) {
+    return {
+        refCount: (counter?.refCount ?? 0) + 1,
+        lastRefAt: refAt,
+    };
+}
+function bumpProjectWikiRef(usage, relPath, source, refAt) {
+    usage.byProjectWikiFile[relPath] = bump(usage.byProjectWikiFile[relPath], refAt);
+    usage.projectWikiRefsBySource[source] = bump(usage.projectWikiRefsBySource[source], refAt);
+    usage.byProjectWikiFileSource[relPath] = usage.byProjectWikiFileSource[relPath] || {};
+    usage.byProjectWikiFileSource[relPath][source] = bump(usage.byProjectWikiFileSource[relPath][source], refAt);
+    usage.projectWikiTotalRefs += 1;
+}
+function isObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function toEffectiveRefs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const refs = [];
+    for (const item of value) {
+        if (typeof item === 'string') {
+            refs.push({ path: item });
+            continue;
+        }
+        if (!isObject(item))
+            continue;
+        const refPath = typeof item.path === 'string'
+            ? item.path
+            : typeof item.file_path === 'string'
+                ? item.file_path
+                : '';
+        if (!refPath)
+            continue;
+        refs.push({
+            path: refPath,
+            score: typeof item.score === 'number' ? item.score : undefined,
+            reason: typeof item.reason === 'string' ? item.reason : undefined,
+        });
+    }
+    return refs;
+}
+function extractProjectWikiRefEvent(stdinData, toolInput) {
+    const candidates = [stdinData, toolInput].filter(Boolean);
+    for (const candidate of candidates) {
+        const refs = toEffectiveRefs(candidate.projectWikiEffectiveRefs
+            ?? candidate.project_wiki_effective_refs
+            ?? candidate.effectiveRefs
+            ?? candidate.effective_refs);
+        if (refs.length === 0)
+            continue;
+        return {
+            source: typeof candidate.source === 'string' ? candidate.source : 'llmwiki',
+            query: typeof candidate.query === 'string' ? candidate.query : undefined,
+            project: typeof candidate.project === 'string' ? candidate.project : undefined,
+            effectiveRefs: refs,
+        };
+    }
+    return null;
+}
+function collectStringValues(value, output = []) {
+    if (typeof value === 'string') {
+        output.push(value);
+        return output;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectStringValues(item, output);
+        return output;
+    }
+    if (isObject(value)) {
+        for (const item of Object.values(value))
+            collectStringValues(item, output);
+    }
+    return output;
+}
+function extractProjectWikiPaths(text) {
+    const matches = text.match(/[^\s"'`<>]*\.project-wiki\/[^\s"'`<>]*?\.md/g) || [];
+    return matches
+        .map((item) => item.replace(/[),.;:，。；：]+$/g, ''))
+        .filter(Boolean);
+}
+export function extractLlmwikiEffectiveRefsFromHookInput(stdinData) {
+    const toolInput = stdinData.tool_input;
+    const command = typeof toolInput?.command === 'string' ? toolInput.command : '';
+    if (!/\bllmwiki\b/.test(command))
+        return [];
+    const toolResult = stdinData.tool_result;
+    const searchText = [
+        command,
+        ...collectStringValues(toolResult),
+    ].join('\n');
+    return Array.from(new Set(extractProjectWikiPaths(searchText))).map((refPath) => ({
+        path: refPath,
+        reason: 'llmwiki query result referenced by Bash output',
+    }));
+}
+/**
+ * 上报 llmwiki 召回后被实际使用的 ProjectWiki 文档。
+ * 只统计调用方传入的 effectiveRefs，不统计全部召回结果；同一次事件内同一路径去重。
+ *
+ * @returns 实际累加的唯一文档数
+ */
+export async function reportProjectWikiRefs(knowledgeDir, event) {
+    const repoRoot = path.dirname(path.dirname(path.resolve(knowledgeDir)));
+    const source = event.source || 'llmwiki';
+    const refAt = event.refAt || getBeijingTime();
+    const uniqueRefs = new Set();
+    for (const ref of event.effectiveRefs || []) {
+        const relPath = normalizeProjectWikiFile(repoRoot, ref.path);
+        if (relPath)
+            uniqueRefs.add(relPath);
+    }
+    if (uniqueRefs.size === 0)
+        return 0;
+    try {
+        const usage = await readUsageStats(knowledgeDir);
+        for (const relPath of uniqueRefs) {
+            bumpProjectWikiRef(usage, relPath, source, refAt);
+        }
+        usage.lastUpdatedAt = refAt;
+        await FileSystemUtils.createDirectory(path.dirname(getUsagePath(knowledgeDir)));
+        await atomicWriteJson(getUsagePath(knowledgeDir), usage);
+        return uniqueRefs.size;
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * 清晰可复用的上报接口：累加一次引用。
  *  - filePath 未命中 knowledge/ 三类目录 → no-op 返回 false。
@@ -106,7 +251,7 @@ function matchProjectWikiFile(repoRoot, filePath) {
 export async function reportKnowledgeRef(knowledgeDir, event) {
     const relPath = matchKnowledgeFile(knowledgeDir, event.filePath);
     const repoRoot = path.dirname(path.dirname(path.resolve(knowledgeDir)));
-    const projectWikiRelPath = matchProjectWikiFile(repoRoot, event.filePath);
+    const projectWikiRelPath = normalizeProjectWikiFile(repoRoot, event.filePath);
     if (!relPath && !projectWikiRelPath)
         return false;
     const refAt = event.refAt || getBeijingTime();
@@ -124,19 +269,14 @@ export async function reportKnowledgeRef(knowledgeDir, event) {
         }
     try {
         const usage = await readUsageStats(knowledgeDir);
-        const bump = (counter) => ({
-            refCount: (counter?.refCount ?? 0) + 1,
-            lastRefAt: refAt,
-        });
         if (relPath) {
-            usage.byFile[relPath] = bump(usage.byFile[relPath]);
+            usage.byFile[relPath] = bump(usage.byFile[relPath], refAt);
             if (id)
-                usage.byId[id] = bump(usage.byId[id]);
+                usage.byId[id] = bump(usage.byId[id], refAt);
             usage.totalRefs += 1;
         }
         if (projectWikiRelPath) {
-            usage.byProjectWikiFile[projectWikiRelPath] = bump(usage.byProjectWikiFile[projectWikiRelPath]);
-            usage.projectWikiTotalRefs += 1;
+            bumpProjectWikiRef(usage, projectWikiRelPath, 'file', refAt);
         }
         usage.lastUpdatedAt = refAt;
         await FileSystemUtils.createDirectory(path.dirname(getUsagePath(knowledgeDir)));
@@ -173,11 +313,20 @@ export async function knowledgeUsageHook(options) {
     }
     const toolInput = stdinData.tool_input;
     const filePath = toolInput?.file_path || toolInput?.path || options.file || '';
-    if (filePath) {
+    const projectWikiRefEvent = extractProjectWikiRefEvent(stdinData, toolInput) || {
+        source: 'llmwiki',
+        effectiveRefs: extractLlmwikiEffectiveRefsFromHookInput(stdinData),
+    };
+    if (filePath || projectWikiRefEvent.effectiveRefs.length > 0) {
         try {
             const repoRoot = resolveZhuanSpecRoot(process.cwd());
             const knowledgeDir = path.join(repoRoot, 'zhuanspec', 'knowledge');
-            await reportKnowledgeRef(knowledgeDir, { filePath });
+            if (projectWikiRefEvent.effectiveRefs.length > 0) {
+                await reportProjectWikiRefs(knowledgeDir, projectWikiRefEvent);
+            }
+            if (filePath) {
+                await reportKnowledgeRef(knowledgeDir, { filePath });
+            }
         }
         catch {
             // 旁路 hook 永不抛错

package/dist/core/init.js

@@ -1495,7 +1495,7 @@ export class InitCommand {
                         ],
                     },
                     {
-                        matcher: 'Read|Grep|Glob',
+                        matcher: 'Read|Grep|Glob|Bash',
                         hooks: [
                             {
                                 type: 'command',

package/dist/core/metrics/knowledge-funnel.d.ts

@@ -30,6 +30,8 @@ export interface FunnelStats {
     projectWikiReferencedRefs: number;
     /** ProjectWiki 被引用数按 service 聚合 */
     projectWikiReferencedRefsByService: Record<string, number>;
+    /** ProjectWiki 被引用数按来源聚合，如 file / llmwiki */
+    projectWikiReferencedRefsBySource: Record<string, number>;
     /** 五跳转化率（0~1，分母为 0 记 0） */
     conversions: {
         signalToAsked: number;

package/dist/core/metrics/knowledge-funnel.js

@@ -104,6 +104,13 @@ function aggregateProjectWikiRefsByService(byProjectWikiFile) {
     }
     return Object.fromEntries(Object.entries(byService).sort(([a], [b]) => a.localeCompare(b)));
 }
+function aggregateCounters(counters) {
+    const result = {};
+    for (const [key, counter] of Object.entries(counters)) {
+        result[key] = counter.refCount ?? 0;
+    }
+    return Object.fromEntries(Object.entries(result).sort(([a], [b]) => a.localeCompare(b)));
+}
 /**
  * 顶层聚合：拼装 FunnelStats。
  * @param archivedEntries 落库数（由调用方传入 stats.total，避免重复 scanKnowledgeEntries）
@@ -114,6 +121,7 @@ export async function computeFunnelStats(zhuanspecDir, knowledgeDir, archivedEnt
     const referencedRefs = usage.totalRefs;
     const projectWikiReferencedRefs = usage.projectWikiTotalRefs;
     const projectWikiReferencedRefsByService = aggregateProjectWikiRefsByService(usage.byProjectWikiFile);
+    const projectWikiReferencedRefsBySource = aggregateCounters(usage.projectWikiRefsBySource);
     const { correctionSignals, askedPitfalls, scannedChanges } = changeScan;
     return {
         correctionSignals,
@@ -122,6 +130,7 @@ export async function computeFunnelStats(zhuanspecDir, knowledgeDir, archivedEnt
         referencedRefs,
         projectWikiReferencedRefs,
         projectWikiReferencedRefsByService,
+        projectWikiReferencedRefsBySource,
         conversions: {
             signalToAsked: rate(askedPitfalls, correctionSignals),
             askedToArchived: rate(archivedEntries, askedPitfalls),

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

@@ -62,7 +62,7 @@ const CODEX_DEFAULT_HOOKS = [
     },
     {
         event: 'PostToolUse',
-        matcher: 'Read|Grep|Glob',
+        matcher: 'Read|Grep|Glob|Bash',
         command: 'ZHUANSPEC_HOST=codex zhuanspec-hook knowledge-usage --json',
     },
     {

package/package.json

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