@zhuan-ai/zhuanspec 2.16.6 → 2.17.0

package/dist/cli/hooks.js

@@ -15,6 +15,7 @@ import { initHook } from '../core/hooks/init.js';
 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 { summarizeHook } from '../core/hooks/summarize.js';
 import { runUserInputHook } from '../core/hooks/user-input-hook.js';
 import { preArchiveHook } from '../core/hooks/pre-archive.js';
@@ -94,6 +95,15 @@ program
     .action(async (options) => {
     await collectKnowledgeHook(options);
 });
+// PostToolUse hook - knowledge usage（引用上报，旁路指标）
+program
+    .command('knowledge-usage')
+    .description('PostToolUse hook - 记录 AI 引用 knowledge/ 知识文件的次数（旁路指标）')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--file <path>', 'File that was read (override stdin tool_input.file_path)')
+    .action(async (options) => {
+    await knowledgeUsageHook(options);
+});
 // Stop hook
 program
     .command('summarize')

package/dist/cli/index.js

@@ -21,6 +21,7 @@ import { discoverSkills, formatSkillsList } from '../core/skill-discovery.js';
 import { registerConfigCommand } from '../commands/config.js';
 import { registerArtifactWorkflowCommands } from '../commands/artifact-workflow.js';
 import { DesignCommand } from '../commands/design.js';
+import { registerKnowledgeCommands } from '../commands/knowledge.js';
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
@@ -635,5 +636,8 @@ program
 });
 // Register artifact workflow commands
 registerArtifactWorkflowCommands(program);
+// Register knowledge management commands (reindex, stats)
+const knowledgeCmd = program.command('knowledge').description('管理项目知识库 zhuanspec/knowledge/');
+registerKnowledgeCommands(knowledgeCmd);
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/commands/knowledge.d.ts

@@ -1,19 +1,29 @@
 /**
  * Knowledge Command
  *
- * 管理项目级知识库 zhuanspec/knowledge/。当前仅提供 reindex 子命令：
+ * 管理项目级知识库 zhuanspec/knowledge/。提供以下子命令：
  * - reindex：扫描三类目录下的 *.md，解析 Front Matter，重建 index.md 三分区
  *   （保留 `## Archive Log` 既有内容）。用于回补历史漂移。
+ * - stats：输出知识库画像（条数/三分区分布/完整率/缺字段清单 + 沉淀漏斗指标），支持 --json。
  */
 import { Command } from 'commander';
 interface ReindexOptions {
     dryRun?: boolean;
 }
+interface StatsOptions {
+    json?: boolean;
+}
 export declare class KnowledgeCommand {
     reindex(options?: ReindexOptions): Promise<void>;
+    stats(options?: StatsOptions): Promise<void>;
+    /** 打印知识库画像区块（人类可读）。 */
+    private printKnowledgeOverview;
+    /** 打印沉淀漏斗区块（人类可读）。 */
+    private printFunnel;
+    private printServiceBreakdown;
 }
 /**
- * 在给定的 parent commander Command 上挂载 `reindex` 子命令。
+ * 在给定的 parent commander Command 上挂载 knowledge 子命令。
  * 父命令由 cli/index.ts 创建，形如 `zhuanspec knowledge`。
  */
 export declare function registerKnowledgeCommands(parent: Command): void;

package/dist/commands/knowledge.js

@@ -1,15 +1,119 @@
 /**
  * Knowledge Command
  *
- * 管理项目级知识库 zhuanspec/knowledge/。当前仅提供 reindex 子命令：
+ * 管理项目级知识库 zhuanspec/knowledge/。提供以下子命令：
  * - reindex：扫描三类目录下的 *.md，解析 Front Matter，重建 index.md 三分区
  *   （保留 `## Archive Log` 既有内容）。用于回补历史漂移。
+ * - stats：输出知识库画像（条数/三分区分布/完整率/缺字段清单 + 沉淀漏斗指标），支持 --json。
  */
 import path from 'path';
+import { promises as fs } from 'fs';
 import chalk from 'chalk';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { resolveZhuanSpecRoot } from '../utils/resolve-root.js';
 import { rebuildIndexContent, scanKnowledgeEntries, } from '../core/hooks/knowledge-index.js';
+import { computeFunnelStats } from '../core/metrics/knowledge-funnel.js';
+const PROJECT_WIKI_FEATURE_MARKERS = ['功能说明：', '功能说明**'];
+const PROJECT_WIKI_EXCLUDED_DIRS = new Set([
+    '.git',
+    '.hg',
+    '.svn',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    'changes',
+    'specs',
+    'knowledge',
+    'test',
+]);
+async function listProjectWikiDirs(rootDir) {
+    const result = [];
+    async function visit(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.name === '.project-wiki') {
+                result.push(fullPath);
+                continue;
+            }
+            if (PROJECT_WIKI_EXCLUDED_DIRS.has(entry.name))
+                continue;
+            await visit(fullPath);
+        }
+    }
+    await visit(rootDir);
+    return result;
+}
+async function listMarkdownFiles(rootDir) {
+    const result = [];
+    async function visit(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await visit(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                result.push(fullPath);
+            }
+        }
+    }
+    await visit(rootDir);
+    return result;
+}
+function countLiteralOccurrences(text, literal) {
+    if (!literal)
+        return 0;
+    let count = 0;
+    let index = text.indexOf(literal);
+    while (index !== -1) {
+        count += 1;
+        index = text.indexOf(literal, index + literal.length);
+    }
+    return count;
+}
+function countProjectWikiFeatureMarkers(text) {
+    return PROJECT_WIKI_FEATURE_MARKERS.reduce((total, marker) => total + countLiteralOccurrences(text, marker), 0);
+}
+async function computeProjectWikiStats(repoRoot) {
+    let total = 0;
+    const byService = {};
+    const wikiDirs = await listProjectWikiDirs(repoRoot);
+    for (const wikiDir of wikiDirs) {
+        const service = path.basename(path.dirname(wikiDir));
+        const markdownFiles = await listMarkdownFiles(wikiDir);
+        for (const file of markdownFiles) {
+            try {
+                const content = await FileSystemUtils.readFile(file);
+                const count = countProjectWikiFeatureMarkers(content);
+                total += count;
+                byService[service] = (byService[service] ?? 0) + count;
+            }
+            catch {
+                // ProjectWiki stats are informational; unreadable files should not fail stats.
+            }
+        }
+    }
+    return {
+        total,
+        byService: Object.fromEntries(Object.entries(byService).sort(([a], [b]) => a.localeCompare(b))),
+    };
+}
 export class KnowledgeCommand {
     async reindex(options = {}) {
         const repoRoot = resolveZhuanSpecRoot(process.cwd());
@@ -25,7 +129,6 @@ export class KnowledgeCommand {
             ? await FileSystemUtils.readFile(indexPath)
             : null;
         const rebuilt = rebuildIndexContent(scan, existing);
-        // 输出扫描摘要
         const counts = {
             troubleshooting: scan.entries.filter((e) => e.category === 'troubleshooting').length,
             bestPractices: scan.entries.filter((e) => e.category === 'best-practices').length,
@@ -35,6 +138,11 @@ export class KnowledgeCommand {
         console.log(chalk.gray(`  - troubleshooting        : ${counts.troubleshooting} 条`));
         console.log(chalk.gray(`  - best-practices         : ${counts.bestPractices} 条`));
         console.log(chalk.gray(`  - implicit-conventions   : ${counts.implicitConventions} 条`));
+        if (scan.errors.length > 0) {
+            console.log(chalk.red(`\n✗ 发现 ${scan.errors.length} 条 Front Matter 严重缺失（YAML 格式缺 id/title）：`));
+            for (const e of scan.errors)
+                console.log(chalk.red(`  ${e}`));
+        }
         if (scan.warnings.length > 0) {
             console.log(chalk.yellow(`\n⚠ 发现 ${scan.warnings.length} 条 Front Matter 不完整，建议尽快补齐：`));
             for (const w of scan.warnings) {
@@ -55,9 +163,160 @@ export class KnowledgeCommand {
         console.log(chalk.green(`\n✓ 已重建 ${path.relative(process.cwd(), indexPath)}`));
         console.log(chalk.gray('  （## Archive Log 既有内容已保留）'));
     }
+    async stats(options = {}) {
+        const repoRoot = resolveZhuanSpecRoot(process.cwd());
+        const zhuanspecDir = path.join(repoRoot, 'zhuanspec');
+        const knowledgeDir = path.join(zhuanspecDir, 'knowledge');
+        const projectWiki = await computeProjectWikiStats(repoRoot);
+        if (!(await FileSystemUtils.directoryExists(knowledgeDir))) {
+            // 知识目录不存在：仍输出漏斗（纠偏信号可能已产生，落库数为 0）
+            const funnel = await computeFunnelStats(zhuanspecDir, knowledgeDir, 0);
+            if (options.json) {
+                const empty = {
+                    total: projectWiki.total,
+                    byCategory: { projectWiki: projectWiki.total },
+                    yamlCount: 0, legacyCount: 0, deprecatedCount: 0,
+                    completenessRate: 0, missingFields: [], errors: [], warnings: [], projectWiki, funnel,
+                };
+                console.log(JSON.stringify(empty, null, 2));
+            }
+            else {
+                console.log(chalk.yellow('⚠ 知识目录不存在，尚未沉淀任何项目知识。'));
+                this.printKnowledgeOverview({
+                    total: projectWiki.total,
+                    byCategory: { projectWiki: projectWiki.total },
+                    yamlCount: 0,
+                    legacyCount: 0,
+                    deprecatedCount: 0,
+                    completenessRate: 0,
+                    projectWiki,
+                });
+                this.printFunnel(funnel);
+            }
+            return;
+        }
+        const scan = await scanKnowledgeEntries(knowledgeDir);
+        const { entries, warnings, errors } = scan;
+        const byCategory = {
+            troubleshooting: entries.filter((e) => e.category === 'troubleshooting').length,
+            'best-practices': entries.filter((e) => e.category === 'best-practices').length,
+            'implicit-conventions': entries.filter((e) => e.category === 'implicit-conventions').length,
+            projectWiki: projectWiki.total,
+        };
+        const knowledgeTotal = entries.length;
+        const overviewTotal = knowledgeTotal + projectWiki.total;
+        // 完整率：无任何 warning/error 的条目 / 总条目
+        const problemFiles = new Set([
+            ...warnings.map((w) => w.match(/\[WARN\] ([^\s]+)/)?.[1] ?? ''),
+            ...errors.map((e) => e.match(/\[ERROR\] ([^\s]+)/)?.[1] ?? ''),
+        ].filter(Boolean));
+        const completeCount = entries.length - problemFiles.size;
+        const completenessRate = entries.length > 0
+            ? Math.round((completeCount / entries.length) * 100)
+            : 100;
+        // 按文件聚合缺失字段清单
+        const missingMap = new Map();
+        for (const line of [...errors, ...warnings]) {
+            const m = line.match(/\[(ERROR|WARN)\] ([^\s]+) (.+)/);
+            if (!m)
+                continue;
+            const file = m[2];
+            const reason = m[3];
+            if (!missingMap.has(file))
+                missingMap.set(file, []);
+            missingMap.get(file).push(reason);
+        }
+        const missingFields = Array.from(missingMap.entries()).map(([file, missing]) => ({ file, missing }));
+        const funnel = await computeFunnelStats(zhuanspecDir, knowledgeDir, entries.length);
+        const output = {
+            total: overviewTotal,
+            byCategory,
+            yamlCount: entries.filter((e) => e.id).length,
+            legacyCount: entries.filter((e) => !e.id).length,
+            deprecatedCount: entries.filter((e) => e.status === 'deprecated').length,
+            completenessRate,
+            missingFields,
+            errors,
+            warnings,
+            projectWiki,
+            funnel,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        this.printKnowledgeOverview({
+            total: output.total,
+            byCategory,
+            yamlCount: output.yamlCount,
+            legacyCount: output.legacyCount,
+            deprecatedCount: output.deprecatedCount,
+            completenessRate,
+            projectWiki,
+        });
+        if (errors.length > 0) {
+            console.log(chalk.red(`\n  ✗ 严重缺失 ${errors.length} 条（YAML 格式缺 id/title）:`));
+            for (const { file, missing } of missingFields.filter((f) => errors.some((e) => e.includes(f.file)))) {
+                console.log(chalk.red(`    ${file}: ${missing.join('; ')}`));
+            }
+        }
+        if (warnings.length > 0) {
+            console.log(chalk.yellow(`\n  ⚠ 软问题 ${warnings.length} 条（缺关键词/适用场景）:`));
+            for (const { file, missing } of missingFields.filter((f) => !errors.some((e) => e.includes(f.file)))) {
+                console.log(chalk.yellow(`    ${file}: ${missing.join('; ')}`));
+            }
+        }
+        if (errors.length === 0 && warnings.length === 0) {
+            console.log(chalk.green('\n  ✓ 所有条目 Front Matter 完整。'));
+        }
+        this.printFunnel(funnel);
+        console.log();
+    }
+    /** 打印知识库画像区块（人类可读）。 */
+    printKnowledgeOverview(output) {
+        console.log(chalk.cyan('\n📚 知识库画像'));
+        console.log(chalk.gray('─────────────────────────────────'));
+        console.log(chalk.white(`  总条数             : ${output.total}`));
+        console.log(chalk.gray(`  troubleshooting    : ${output.byCategory['troubleshooting'] ?? 0} 条`));
+        console.log(chalk.gray(`  best-practices     : ${output.byCategory['best-practices'] ?? 0} 条`));
+        console.log(chalk.gray(`  implicit-conv.     : ${output.byCategory['implicit-conventions'] ?? 0} 条`));
+        console.log(chalk.gray(`  projectWiki        : ${output.byCategory['projectWiki'] ?? 0} 条`));
+        if (output.projectWiki) {
+            this.printServiceBreakdown(output.projectWiki.byService, '条');
+        }
+        console.log(chalk.gray('─────────────────────────────────'));
+        console.log(chalk.white(`  YAML 新格式        : ${output.yamlCount} 条`));
+        console.log(chalk.white(`  旧散文格式         : ${output.legacyCount} 条`));
+        console.log(chalk.white(`  已失效(deprecated) : ${output.deprecatedCount} 条`));
+        console.log(chalk.white(`  Front Matter 完整率 : ${output.completenessRate}%`));
+    }
+    /** 打印沉淀漏斗区块（人类可读）。 */
+    printFunnel(funnel) {
+        const pct = (r) => `${(r * 100).toFixed(2)}%`;
+        console.log(chalk.cyan('\n📊 沉淀漏斗'));
+        console.log(chalk.gray('─────────────────────────────────'));
+        console.log(chalk.white(`  ① 纠偏信号数       : ${funnel.correctionSignals}`));
+        console.log(chalk.white(`  ② 追问数           : ${funnel.askedPitfalls}`));
+        console.log(chalk.white(`  ③ 落库数           : ${funnel.archivedEntries}`));
+        console.log(chalk.white(`  ④ 被引用数         : ${funnel.referencedRefs}`));
+        console.log(chalk.white(`  ⑤ ProjectWiki 被引用数 : ${funnel.projectWikiReferencedRefs}`));
+        this.printServiceBreakdown(funnel.projectWikiReferencedRefsByService, '');
+        console.log(chalk.gray('─────────────────────────────────'));
+        console.log(chalk.gray(`  ①→② 信号→追问      : ${pct(funnel.conversions.signalToAsked)}`));
+        console.log(chalk.gray(`  ②→③ 追问→落库      : ${pct(funnel.conversions.askedToArchived)}`));
+        console.log(chalk.gray(`  ③→④ 落库→引用      : ${pct(funnel.conversions.archivedToReferenced)}`));
+        console.log(chalk.gray(`  ①→③ 端到端落库     : ${pct(funnel.conversions.signalToArchived)}`));
+        console.log(chalk.gray(`  ①→④ 端到端引用     : ${pct(funnel.conversions.signalToReferenced)}`));
+        console.log(chalk.gray(`  （扫描 change 数：${funnel.scannedChanges}）`));
+    }
+    printServiceBreakdown(byService, suffix) {
+        for (const [service, count] of Object.entries(byService)) {
+            console.log(chalk.gray(`    ${service.padEnd(17)}: ${count}${suffix ? ` ${suffix}` : ''}`));
+        }
+    }
 }
 /**
- * 在给定的 parent commander Command 上挂载 `reindex` 子命令。
+ * 在给定的 parent commander Command 上挂载 knowledge 子命令。
  * 父命令由 cli/index.ts 创建，形如 `zhuanspec knowledge`。
  */
 export function registerKnowledgeCommands(parent) {
@@ -76,5 +335,20 @@ export function registerKnowledgeCommands(parent) {
             process.exit(1);
         }
     });
+    parent
+        .command('stats')
+        .description('输出知识库画像：总条数、三分区分布、Front Matter 完整率、缺字段清单')
+        .option('--json', '以 JSON 格式输出（供脚本/analytics 消费）')
+        .action(async (options) => {
+        try {
+            const cmd = new KnowledgeCommand();
+            await cmd.stats(options ?? {});
+        }
+        catch (error) {
+            console.log();
+            console.log(chalk.red(`✗ stats 失败: ${error.message}`));
+            process.exit(1);
+        }
+    });
 }
 //# sourceMappingURL=knowledge.js.map

package/dist/core/hooks/context-load-hook.js

@@ -20,6 +20,8 @@ function determineResourceType(filePath) {
         return 'spec';
     if (filePath.includes('zhuanspec/knowledge/'))
         return 'knowledge';
+    if (filePath.includes('.project-wiki/'))
+        return 'project-wiki';
     if (filePath.includes('AGENTS.md'))
         return 'AGENTS.md';
     if (filePath.includes('CLAUDE.md'))

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

@@ -11,6 +11,10 @@
 /** 知识库三类分类目录（不得新增） */
 export type KnowledgeCategory = 'troubleshooting' | 'best-practices' | 'implicit-conventions';
 export declare const KNOWLEDGE_CATEGORIES: readonly KnowledgeCategory[];
+/** 严重度（YAML schema 字段，缺省视为 medium） */
+export type KnowledgeSeverity = 'high' | 'medium' | 'low';
+/** 知识生命周期状态（YAML schema 字段，缺省视为 active） */
+export type KnowledgeStatus = 'active' | 'deprecated';
 /** 单条知识条目（来源于知识文件的 Front Matter 解析） */
 export interface KnowledgeEntry {
     category: KnowledgeCategory;
@@ -22,6 +26,12 @@ export interface KnowledgeEntry {
     keywords: string;
     /** 适用场景：一句话"何时引用本条知识" */
     useCase: string;
+    /** 稳定主键（YAML 格式才有；旧格式为空） */
+    id?: string;
+    /** 严重度（YAML 格式才有） */
+    severity?: KnowledgeSeverity;
+    /** 生命周期状态（YAML 格式才有，缺省 active） */
+    status?: KnowledgeStatus;
 }
 /** Front Matter 解析结果 */
 export interface KnowledgeFrontMatter {
@@ -30,6 +40,16 @@ export interface KnowledgeFrontMatter {
     useCase: string;
     missingUseCase: boolean;
     missingKeywords: boolean;
+    /** 是否为新版 YAML frontmatter（`---` 包裹）；false 表示旧版散文式 */
+    isYaml: boolean;
+    /** 稳定主键（仅 YAML 格式解析） */
+    id: string;
+    /** YAML 格式下缺少 id（强校验依据） */
+    missingId: boolean;
+    /** 严重度（仅 YAML 格式解析，缺省 medium） */
+    severity: KnowledgeSeverity;
+    /** 生命周期状态（仅 YAML 格式解析，缺省 active） */
+    status: KnowledgeStatus;
 }
 /**
  * 生成默认的空 index.md 骨架（含三分区 + Archive Log）。
@@ -58,21 +78,53 @@ export declare function readOrInitIndex(indexPath: string): Promise<string>;
 export declare function appendIndexEntry(indexPath: string, entry: KnowledgeEntry): Promise<boolean>;
 /**
  * 从一段 markdown 文本中解析知识条目 Front Matter。
- * 支持项目现行的 `**字段**: 值` 样式；字段可选，缺失时返回对应 missing 标记。
+ *
+ * 两种格式自动识别：
+ *  - **新版 YAML**（`---` 包裹）：解析 id / title / keywords / trigger / severity / status，
+ *    适用场景优先取 `use_case` 字段，否则回退正文 `## 适用场景` 首行；缺 id 记 missingId。
+ *  - **旧版散文**（无 frontmatter）：沿用 `# 标题` + `**关键词**:` + `**适用场景**:`，
+ *    不参与 id 强校验，保证历史知识文件向后兼容。
  */
 export declare function parseFrontMatter(markdown: string): KnowledgeFrontMatter;
 /**
- * 扫描结果：每类目录下发现的知识条目（含缺字段告警）。
+ * 从归档文档文本解析 deprecates 声明（哪些知识 id 被本次 change 推翻）。
+ * 支持两种来源（任一命中即收集，去重）：
+ *  1. YAML frontmatter 顶层 `deprecates: bp-x, bp-y` 或数组形式
+ *  2. 正文行 `deprecates: bp-x, bp-y`（大小写不敏感，逗号/中文逗号/空格分隔）
+ * @returns 去重后的 id 列表
+ */
+export declare function parseDeprecatesDeclaration(markdown: string): string[];
+/**
+ * 扫描结果：每类目录下发现的知识条目。
+ *  - warnings：软问题（缺关键词/适用场景、旧格式缺标题），有兜底、不阻断。
+ *  - errors：硬问题（YAML 格式缺 id / title），强校验依据，供命令决定是否阻断。
  */
 export interface ScanResult {
     entries: KnowledgeEntry[];
     warnings: string[];
+    errors: string[];
 }
 /**
  * 扫描 knowledge/{troubleshooting,best-practices,implicit-conventions}/*.md，
  * 解析 Front Matter 组装 KnowledgeEntry 列表，遇缺字段记录 warning（不阻断）。
  */
 export declare function scanKnowledgeEntries(knowledgeDir: string): Promise<ScanResult>;
+/**
+ * 在 knowledgeDir 内按 id 定位知识文件绝对路径（扫三类目录匹配 frontmatter.id）。
+ * 命中多个同 id 时返回首个（id 应唯一，重复属数据问题，由 scan 的 missingId 校验体系覆盖）。
+ */
+export declare function findEntryFileById(knowledgeDir: string, id: string): Promise<string | null>;
+/**
+ * 将指定知识文件的 YAML frontmatter status 改为目标值，保留正文与其他字段。
+ *
+ * 算法（不做整体 YAML 序列化，避免丢注释/改键序/改引号风格破坏文件）：
+ *  1. FRONT_MATTER_RE 切出 yaml 块与正文 body；无 frontmatter（旧散文式）→ 返回 false，不动正文。
+ *  2. 仅当存在 `status:` 行时替换该行值，否则在 yaml 块末尾追加 `status: <status>`。
+ *  3. 改写后用 parseFrontMatter 复核 status 命中目标值再落盘（自检，防正则误伤）。
+ *
+ * @returns 是否实际写入（已是目标状态或旧散文式均返回 false）
+ */
+export declare function setEntryStatus(filePath: string, status: KnowledgeStatus): Promise<boolean>;
 /**
  * 全量重建 index.md 的三大分区（保留 Archive Log 既有内容）。
  * 算法：