@zhuan-ai/zhuanspec 2.16.6 → 2.17.0

package/dist/core/hooks/user-input-hook.js

@@ -70,6 +70,41 @@ function buildCorrectionSignal(content) {
     }
     return { kind: 'none', matchedKeywords: [], isRequirementChange: false };
 }
+/**
+ * 对话经验解决信号检测。
+ *
+ * 设计意图：
+ *   - 只检测「问题已解决/找到根因」语义，不检测「问题存在」（那是 correctionSignal 的职责）。
+ *   - 关键词刻意保守（要求语气有确定性），减少误报——宁可漏报，不要在用户只是描述问题时就触发。
+ *   - 触发后不立即弹窗，只打标；Stop hook 会在会话结束时统一判断是否注入精炼提示。
+ */
+const RESOLUTION_KEYWORDS = [
+    // 中文——明确表达"已解决/已找到"
+    '解决了', '已解决', '找到了', '找到原因', '找到根因',
+    '原因是', '根因是', '根本原因', '问题出在', '问题在于',
+    '定位到了', '定位到问题', '排查出来了', '查清楚了',
+    '原来是', '原来问题', '确认是', '确认原因',
+    // 英文
+    'fixed', 'resolved', 'found the cause', 'found the root cause',
+    'root cause is', 'the issue was', 'the problem was',
+    'figured it out', 'tracked it down',
+];
+const RESOLUTION_CONTEXT_MAX_LEN = 300;
+export function buildResolutionSignal(content) {
+    const lower = content.toLowerCase();
+    const matched = [];
+    for (const kw of RESOLUTION_KEYWORDS) {
+        if (lower.includes(kw.toLowerCase()))
+            matched.push(kw);
+        if (matched.length >= 4)
+            break;
+    }
+    return {
+        detected: matched.length > 0,
+        matchedKeywords: matched,
+        context: matched.length > 0 ? content.slice(0, RESOLUTION_CONTEXT_MAX_LEN) : '',
+    };
+}
 /**
  * Detect trigger type from user input content
  */
@@ -230,6 +265,7 @@ export async function userInputHook(content, responseTimeMs) {
     const progressPath = path.join(metricsDir, 'progress.json');
     // Create input record
     const correctionSignal = buildCorrectionSignal(content);
+    const resolutionSignal = buildResolutionSignal(content);
     const inputRecord = {
         inputId: `input-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
         timestamp: getBeijingTime(),
@@ -240,6 +276,8 @@ export async function userInputHook(content, responseTimeMs) {
         affectedFiles: extractAffectedFiles(content),
         responseTimeMs,
         correctionSignal,
+        // 只有检测到解决信号时才写入，避免 user_inputs.json 膨胀
+        ...(resolutionSignal.detected ? { resolutionSignal } : {}),
     };
     // Load existing user inputs or create new
     let userInputs;

package/dist/core/init.js

@@ -1494,6 +1494,16 @@ export class InitCommand {
                             },
                         ],
                     },
+                    {
+                        matcher: 'Read|Grep|Glob',
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook knowledge-usage --json',
+                                async: true,
+                            },
+                        ],
+                    },
                 ],
                 Stop: [
                     {

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

@@ -0,0 +1,49 @@
+/**
+ * Knowledge Funnel（沉淀漏斗指标）
+ *
+ * 量化「纠偏信号 → 追问 → 落库 → 被引用」四节点漏斗各跳转化率，
+ * 用于回答"知识沉淀机制是否健康、哪一跳流失最多"。
+ *
+ * 数据来源（跨 change 扫描 active + archive）：
+ *  - 纠偏信号数：每个 change 的 metrics/user_inputs.json 中 correctionSignal.kind==='hard'
+ *    && postBaseline===true 的条数（与 collect-knowledge 的口径一致）。
+ *  - 追问数：每个 change 的 metrics/progress.json 中 askedPitfallSaved===true 的 change 数。
+ *  - 落库数：knowledge 三分区现有条目总数（由调用方传入，避免重复扫描）。
+ *  - 被引用数：knowledge/.metrics/usage.json 的 totalRefs。
+ *  - ProjectWiki 被引用数：knowledge/.metrics/usage.json 的 projectWikiTotalRefs。
+ *
+ * 全程容错：任一文件读失败/JSON 损坏均跳过，绝不抛错。
+ */
+/** 纠偏信号判定口径（与 collect-knowledge.ts readCorrectionStats 一致）。 */
+export declare function countHardCorrections(inputs: Array<Record<string, unknown>>): number;
+/** 漏斗统计结果 */
+export interface FunnelStats {
+    /** 纠偏信号数（hard） */
+    correctionSignals: number;
+    /** 追问数（askedPitfallSaved===true 的 change 数） */
+    askedPitfalls: number;
+    /** 落库数（= knowledge 三分区条目总数） */
+    archivedEntries: number;
+    /** 被引用数（usage.json totalRefs） */
+    referencedRefs: number;
+    /** ProjectWiki 被引用数（usage.json projectWikiTotalRefs） */
+    projectWikiReferencedRefs: number;
+    /** ProjectWiki 被引用数按 service 聚合 */
+    projectWikiReferencedRefsByService: Record<string, number>;
+    /** 五跳转化率（0~1，分母为 0 记 0） */
+    conversions: {
+        signalToAsked: number;
+        askedToArchived: number;
+        archivedToReferenced: number;
+        signalToArchived: number;
+        signalToReferenced: number;
+    };
+    /** 扫描到的 change 数（含 archive），用于自检 */
+    scannedChanges: number;
+}
+/**
+ * 顶层聚合：拼装 FunnelStats。
+ * @param archivedEntries 落库数（由调用方传入 stats.total，避免重复 scanKnowledgeEntries）
+ */
+export declare function computeFunnelStats(zhuanspecDir: string, knowledgeDir: string, archivedEntries: number): Promise<FunnelStats>;
+//# sourceMappingURL=knowledge-funnel.d.ts.map

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

@@ -0,0 +1,135 @@
+/**
+ * Knowledge Funnel（沉淀漏斗指标）
+ *
+ * 量化「纠偏信号 → 追问 → 落库 → 被引用」四节点漏斗各跳转化率，
+ * 用于回答"知识沉淀机制是否健康、哪一跳流失最多"。
+ *
+ * 数据来源（跨 change 扫描 active + archive）：
+ *  - 纠偏信号数：每个 change 的 metrics/user_inputs.json 中 correctionSignal.kind==='hard'
+ *    && postBaseline===true 的条数（与 collect-knowledge 的口径一致）。
+ *  - 追问数：每个 change 的 metrics/progress.json 中 askedPitfallSaved===true 的 change 数。
+ *  - 落库数：knowledge 三分区现有条目总数（由调用方传入，避免重复扫描）。
+ *  - 被引用数：knowledge/.metrics/usage.json 的 totalRefs。
+ *  - ProjectWiki 被引用数：knowledge/.metrics/usage.json 的 projectWikiTotalRefs。
+ *
+ * 全程容错：任一文件读失败/JSON 损坏均跳过，绝不抛错。
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { readUsageStats } from '../hooks/knowledge-usage.js';
+/** 纠偏信号判定口径（与 collect-knowledge.ts readCorrectionStats 一致）。 */
+export function countHardCorrections(inputs) {
+    let hard = 0;
+    for (const entry of inputs) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const sig = entry['correctionSignal'];
+        const postBaseline = entry['postBaseline'] === true;
+        if (sig && sig.kind === 'hard' && postBaseline)
+            hard += 1;
+    }
+    return hard;
+}
+/** 安全读取并解析 JSON，失败返回 null。 */
+async function readJsonSafe(filePath) {
+    try {
+        if (!(await FileSystemUtils.fileExists(filePath)))
+            return null;
+        return JSON.parse(await FileSystemUtils.readFile(filePath));
+    }
+    catch {
+        return null;
+    }
+}
+/** 累加单个 change 目录的纠偏信号数与追问数。 */
+async function accumulateChange(metricsDir, acc) {
+    const userInputs = await readJsonSafe(path.join(metricsDir, 'user_inputs.json'));
+    if (userInputs && Array.isArray(userInputs.inputs)) {
+        acc.correctionSignals += countHardCorrections(userInputs.inputs);
+    }
+    const progress = await readJsonSafe(path.join(metricsDir, 'progress.json'));
+    if (progress && progress.askedPitfallSaved === true) {
+        acc.askedPitfalls += 1;
+    }
+    acc.scannedChanges += 1;
+}
+/** 列出目录下的子目录名（容错，失败返回空）。 */
+async function listDirs(dir) {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** 扫描所有 change（active + archive）聚合纠偏信号数与追问数。 */
+async function scanChangeMetrics(zhuanspecDir) {
+    const acc = { correctionSignals: 0, askedPitfalls: 0, scannedChanges: 0 };
+    const changesDir = path.join(zhuanspecDir, 'changes');
+    const archiveDir = path.join(changesDir, 'archive');
+    // active changes（排除 archive 目录本身）
+    for (const id of await listDirs(changesDir)) {
+        if (id === 'archive')
+            continue;
+        await accumulateChange(path.join(changesDir, id, 'metrics'), acc);
+    }
+    // archived changes
+    for (const id of await listDirs(archiveDir)) {
+        await accumulateChange(path.join(archiveDir, id, 'metrics'), acc);
+    }
+    return acc;
+}
+/** 安全转化率：分母为 0 记 0，结果保留 4 位小数。 */
+function rate(numerator, denominator) {
+    if (denominator <= 0)
+        return 0;
+    return Math.round((numerator / denominator) * 10000) / 10000;
+}
+function getProjectWikiServiceName(projectWikiRelPath) {
+    const segments = projectWikiRelPath.split(/[\\/]+/).filter(Boolean);
+    const wikiIndex = segments.indexOf('.project-wiki');
+    if (wikiIndex <= 0)
+        return null;
+    return segments[wikiIndex - 1] || null;
+}
+function aggregateProjectWikiRefsByService(byProjectWikiFile) {
+    const byService = {};
+    for (const [file, counter] of Object.entries(byProjectWikiFile)) {
+        const service = getProjectWikiServiceName(file);
+        if (!service)
+            continue;
+        byService[service] = (byService[service] ?? 0) + (counter.refCount ?? 0);
+    }
+    return Object.fromEntries(Object.entries(byService).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * 顶层聚合：拼装 FunnelStats。
+ * @param archivedEntries 落库数（由调用方传入 stats.total，避免重复 scanKnowledgeEntries）
+ */
+export async function computeFunnelStats(zhuanspecDir, knowledgeDir, archivedEntries) {
+    const changeScan = await scanChangeMetrics(zhuanspecDir);
+    const usage = await readUsageStats(knowledgeDir);
+    const referencedRefs = usage.totalRefs;
+    const projectWikiReferencedRefs = usage.projectWikiTotalRefs;
+    const projectWikiReferencedRefsByService = aggregateProjectWikiRefsByService(usage.byProjectWikiFile);
+    const { correctionSignals, askedPitfalls, scannedChanges } = changeScan;
+    return {
+        correctionSignals,
+        askedPitfalls,
+        archivedEntries,
+        referencedRefs,
+        projectWikiReferencedRefs,
+        projectWikiReferencedRefsByService,
+        conversions: {
+            signalToAsked: rate(askedPitfalls, correctionSignals),
+            askedToArchived: rate(archivedEntries, askedPitfalls),
+            archivedToReferenced: rate(referencedRefs, archivedEntries),
+            signalToArchived: rate(archivedEntries, correctionSignals),
+            signalToReferenced: rate(referencedRefs, correctionSignals),
+        },
+        scannedChanges,
+    };
+}
+//# sourceMappingURL=knowledge-funnel.js.map