@zhuan-ai/zhuanspec 2.16.6 → 2.17.0

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

@@ -10,6 +10,7 @@
  */
 import path from 'path';
 import { promises as fs } from 'fs';
+import { parse as parseYaml } from 'yaml';
 import { FileSystemUtils } from '../../utils/file-system.js';
 export const KNOWLEDGE_CATEGORIES = [
     'troubleshooting',
@@ -28,11 +29,16 @@ const SECTION_COMMENTS = {
     'implicit-conventions': '<!-- 隐式约定 / 默认行为 / 团队惯例，由 post-archive hook 与 skill 共同管理 -->',
 };
 const ARCHIVE_LOG_HEADING = '## Archive Log';
+/** 失效知识折叠区标题与说明 */
+const DEPRECATED_HEADING = '## Deprecated';
+const DEPRECATED_COMMENT = '<!-- 已被后续 change 推翻的失效知识，AI 不应引用；仅作审计留痕 -->';
 const INDEX_HEADER = `# Knowledge Index
 
 > 项目知识索引。AI 在进入任何阶段前应先浏览本文件，根据每条"适用场景"判断是否需要打开对应文件。
 > 入口：所有写入由 \`@skill:zhuanspec:knowledge\` 或 post-archive hook 统一完成，禁止直接 Write/Edit 本目录。
-> 索引漂移时运行 \`zhuanspec knowledge reindex --dry-run\` 查看差异。`;
+> 索引漂移时运行 \`zhuanspec knowledge reindex --dry-run\` 查看差异。
+> ⚠️ AI 只应引用三分区（Troubleshooting / Best Practices / Implicit Conventions）中的条目；
+> \`## Deprecated\` 区为已失效知识，仅作审计留痕，**禁止引用**。`;
 /**
  * 生成默认的空 index.md 骨架（含三分区 + Archive Log）。
  */
@@ -47,7 +53,9 @@ export function buildInitialIndex() {
 export function buildEntryLine(entry) {
     const keywords = entry.keywords.trim() || '（未填写关键词）';
     const useCase = entry.useCase.trim() || '（未填写适用场景）';
-    return `- [${entry.title}](${entry.category}/${entry.fileName}) — ${keywords} · 适用场景：${useCase}`;
+    // high 严重度前置 🔴 标记，便于 AI 浏览索引时优先阅读
+    const sev = entry.severity === 'high' ? '🔴 ' : '';
+    return `- ${sev}[${entry.title}](${entry.category}/${entry.fileName}) — ${keywords} · 适用场景：${useCase}`;
 }
 /**
  * 确保 index.md 含完整三分区骨架；若缺失分区则补齐（不覆盖已有条目与 Archive Log）。
@@ -146,13 +154,65 @@ function insertIntoSection(content, category, line) {
     before.push(line, '');
     return [...before, ...after].join('\n');
 }
+/** 匹配文件开头的 YAML frontmatter 块（`---` 包裹）。 */
+const FRONT_MATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/;
 /**
  * 从一段 markdown 文本中解析知识条目 Front Matter。
- * 支持项目现行的 `**字段**: 值` 样式；字段可选，缺失时返回对应 missing 标记。
+ *
+ * 两种格式自动识别：
+ *  - **新版 YAML**（`---` 包裹）：解析 id / title / keywords / trigger / severity / status，
+ *    适用场景优先取 `use_case` 字段，否则回退正文 `## 适用场景` 首行；缺 id 记 missingId。
+ *  - **旧版散文**（无 frontmatter）：沿用 `# 标题` + `**关键词**:` + `**适用场景**:`，
+ *    不参与 id 强校验，保证历史知识文件向后兼容。
  */
 export function parseFrontMatter(markdown) {
-    const titleMatch = markdown.match(/^#\s+(.+?)\s*$/m);
-    const title = titleMatch ? titleMatch[1].trim() : '';
+    const fmMatch = markdown.match(FRONT_MATTER_RE);
+    if (fmMatch) {
+        return parseYamlFrontMatter(fmMatch[1], markdown.slice(fmMatch[0].length));
+    }
+    return parseLegacyFrontMatter(markdown);
+}
+/** 解析新版 YAML frontmatter。 */
+function parseYamlFrontMatter(yamlText, body) {
+    let data = {};
+    try {
+        const parsed = parseYaml(yamlText);
+        if (parsed && typeof parsed === 'object')
+            data = parsed;
+    }
+    catch {
+        // YAML 解析失败：当作缺字段处理，由上层 scan 记 error
+    }
+    // 判断是否为「知识库专用 YAML」：必须含 id 或 title（或 category/severity/trigger 等专属字段）。
+    // 仅含 name/description/type 等 memory 格式字段的旧文件降级为旧格式解析，避免误报强校验。
+    const knowledgeYamlKeys = ['id', 'title', 'category', 'severity', 'trigger', 'status', 'use_case', 'keywords'];
+    const isKnowledgeYaml = knowledgeYamlKeys.some((k) => k in data);
+    if (!isKnowledgeYaml) {
+        return parseLegacyFrontMatter(body ? `${yamlText}\n${body}` : body);
+    }
+    const trigger = (data.trigger && typeof data.trigger === 'object')
+        ? data.trigger
+        : {};
+    const id = asString(data.id);
+    const title = asString(data.title) || pickHeadingTitle(body);
+    const keywords = normalizeKeywords(data.keywords ?? trigger.keywords);
+    const useCase = asString(data.use_case ?? data['适用场景']) || pickUseCaseFromBody(body);
+    return {
+        title,
+        keywords,
+        useCase,
+        missingUseCase: !useCase,
+        missingKeywords: !keywords,
+        isYaml: true,
+        id,
+        missingId: !id,
+        severity: normalizeSeverity(data.severity),
+        status: data.status === 'deprecated' ? 'deprecated' : 'active',
+    };
+}
+/** 解析旧版散文式 front matter（向后兼容）。 */
+function parseLegacyFrontMatter(markdown) {
+    const title = pickHeadingTitle(markdown);
     const pick = (label) => {
         const re = new RegExp(`\\*\\*${escapeRegex(label)}\\*\\*\\s*[:：]\\s*(.+?)\\s*$`, 'm');
         const m = markdown.match(re);
@@ -166,8 +226,79 @@ export function parseFrontMatter(markdown) {
         useCase,
         missingUseCase: !useCase,
         missingKeywords: !keywords,
+        isYaml: false,
+        id: '',
+        missingId: false, // 旧格式不参与 id 强校验
+        severity: 'medium',
+        status: 'active',
     };
 }
+/**
+ * 从归档文档文本解析 deprecates 声明（哪些知识 id 被本次 change 推翻）。
+ * 支持两种来源（任一命中即收集，去重）：
+ *  1. YAML frontmatter 顶层 `deprecates: bp-x, bp-y` 或数组形式
+ *  2. 正文行 `deprecates: bp-x, bp-y`（大小写不敏感，逗号/中文逗号/空格分隔）
+ * @returns 去重后的 id 列表
+ */
+export function parseDeprecatesDeclaration(markdown) {
+    const ids = new Set();
+    // 1. frontmatter 顶层 deprecates
+    const fmMatch = markdown.match(FRONT_MATTER_RE);
+    if (fmMatch) {
+        try {
+            const data = parseYaml(fmMatch[1]);
+            if (data && 'deprecates' in data) {
+                for (const id of splitDeprecatesValue(data.deprecates))
+                    ids.add(id);
+            }
+        }
+        catch {
+            // 解析失败忽略，继续走正文匹配
+        }
+    }
+    // 2. 正文行 `deprecates: ...`（行首锚定，避免误伤句中出现的字样）
+    const lineRe = /^deprecates\s*[:：]\s*(.+)$/gim;
+    let m;
+    while ((m = lineRe.exec(markdown)) !== null) {
+        for (const id of splitDeprecatesValue(m[1]))
+            ids.add(id);
+    }
+    return Array.from(ids);
+}
+/** 将 deprecates 字段值（字符串/数组）拆成干净的 id 列表。 */
+function splitDeprecatesValue(v) {
+    if (Array.isArray(v))
+        return v.map((x) => String(x).trim()).filter(Boolean);
+    if (typeof v === 'string')
+        return v.split(/[,，\s]+/).map((s) => s.trim()).filter(Boolean);
+    return [];
+}
+/** 取正文首个一级标题 `# xxx`。 */
+function pickHeadingTitle(markdown) {
+    const m = markdown.match(/^#\s+(.+?)\s*$/m);
+    return m ? m[1].trim() : '';
+}
+/** 从正文 `## 适用场景` 段落抓首行非空文本。 */
+function pickUseCaseFromBody(body) {
+    const m = body.match(/^##\s+适用场景\s*\r?\n+\s*([^\n]+?)\s*$/m);
+    return m ? m[1].trim() : '';
+}
+/** keywords 归一化：数组 → 逗号拼接；字符串 → 原样；其他 → 空串。 */
+function normalizeKeywords(v) {
+    if (Array.isArray(v))
+        return v.map((x) => String(x).trim()).filter(Boolean).join(', ');
+    if (typeof v === 'string')
+        return v.trim();
+    return '';
+}
+/** severity 归一化：仅 high/low 生效，其余（含缺省/非法）一律 medium。 */
+function normalizeSeverity(v) {
+    return v === 'high' || v === 'low' ? v : 'medium';
+}
+/** 安全转字符串（null/undefined → 空串）。 */
+function asString(v) {
+    return v === null || v === undefined ? '' : String(v).trim();
+}
 /**
  * 扫描 knowledge/{troubleshooting,best-practices,implicit-conventions}/*.md，
  * 解析 Front Matter 组装 KnowledgeEntry 列表，遇缺字段记录 warning（不阻断）。
@@ -175,6 +306,7 @@ export function parseFrontMatter(markdown) {
 export async function scanKnowledgeEntries(knowledgeDir) {
     const entries = [];
     const warnings = [];
+    const errors = [];
     for (const category of KNOWLEDGE_CATEGORIES) {
         const dir = path.join(knowledgeDir, category);
         if (!(await FileSystemUtils.directoryExists(dir)))
@@ -198,14 +330,24 @@ export async function scanKnowledgeEntries(knowledgeDir) {
                 continue;
             }
             const fm = parseFrontMatter(text);
-            if (!fm.title) {
+            // 强校验仅作用于新版 YAML 文件：缺 id / title 记 error（身份缺失）；
+            // 旧版散文文件一律走 warning 兜底，保证历史知识向后兼容。
+            if (fm.isYaml) {
+                if (fm.missingId) {
+                    errors.push(`[ERROR] ${category}/${file} YAML frontmatter 缺少 id 字段（稳定主键，去重/合并依赖它）`);
+                }
+                if (!fm.title) {
+                    errors.push(`[ERROR] ${category}/${file} YAML frontmatter 缺少 title 字段`);
+                }
+            }
+            else if (!fm.title) {
                 warnings.push(`[WARN] ${category}/${file} 缺少一级标题 (# 标题)，使用文件名兜底`);
             }
             if (fm.missingKeywords) {
-                warnings.push(`[WARN] ${category}/${file} 缺少 **关键词** 字段`);
+                warnings.push(`[WARN] ${category}/${file} 缺少关键词（YAML keywords/trigger.keywords 或 **关键词** 字段）`);
             }
             if (fm.missingUseCase) {
-                warnings.push(`[WARN] ${category}/${file} 缺少 **适用场景** 字段（请尽快补齐）`);
+                warnings.push(`[WARN] ${category}/${file} 缺少适用场景（YAML use_case / 正文 ## 适用场景 / **适用场景** 字段）`);
             }
             const firstKeyword = fm.keywords ? fm.keywords.split(/[,，]/)[0].trim() : '';
             entries.push({
@@ -215,10 +357,87 @@ export async function scanKnowledgeEntries(knowledgeDir) {
                 keywords: fm.keywords,
                 // 兜底：适用场景缺失时用"首关键词相关任务"
                 useCase: fm.useCase || (firstKeyword ? `涉及 ${firstKeyword} 相关任务时` : '（未填写适用场景，待补齐）'),
+                id: fm.id || undefined,
+                severity: fm.isYaml ? fm.severity : undefined,
+                status: fm.isYaml ? fm.status : undefined,
             });
         }
     }
-    return { entries, warnings };
+    return { entries, warnings, errors };
+}
+/**
+ * 在 knowledgeDir 内按 id 定位知识文件绝对路径（扫三类目录匹配 frontmatter.id）。
+ * 命中多个同 id 时返回首个（id 应唯一，重复属数据问题，由 scan 的 missingId 校验体系覆盖）。
+ */
+export async function findEntryFileById(knowledgeDir, id) {
+    if (!id)
+        return null;
+    for (const category of KNOWLEDGE_CATEGORIES) {
+        const dir = path.join(knowledgeDir, category);
+        if (!(await FileSystemUtils.directoryExists(dir)))
+            continue;
+        let files = [];
+        try {
+            files = (await fs.readdir(dir)).filter((f) => f.endsWith('.md') && !f.startsWith('.'));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            const full = path.join(dir, file);
+            try {
+                const fm = parseFrontMatter(await FileSystemUtils.readFile(full));
+                if (fm.isYaml && fm.id === id)
+                    return full;
+            }
+            catch {
+                // 读失败跳过
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 将指定知识文件的 YAML frontmatter status 改为目标值，保留正文与其他字段。
+ *
+ * 算法（不做整体 YAML 序列化，避免丢注释/改键序/改引号风格破坏文件）：
+ *  1. FRONT_MATTER_RE 切出 yaml 块与正文 body；无 frontmatter（旧散文式）→ 返回 false，不动正文。
+ *  2. 仅当存在 `status:` 行时替换该行值，否则在 yaml 块末尾追加 `status: <status>`。
+ *  3. 改写后用 parseFrontMatter 复核 status 命中目标值再落盘（自检，防正则误伤）。
+ *
+ * @returns 是否实际写入（已是目标状态或旧散文式均返回 false）
+ */
+export async function setEntryStatus(filePath, status) {
+    let content;
+    try {
+        content = await FileSystemUtils.readFile(filePath);
+    }
+    catch {
+        return false;
+    }
+    const fmMatch = content.match(FRONT_MATTER_RE);
+    if (!fmMatch)
+        return false; // 旧散文式：绝不改正文
+    // 幂等：已是目标状态
+    const current = parseFrontMatter(content);
+    if (current.isYaml && current.status === status)
+        return false;
+    const yamlText = fmMatch[1];
+    const body = content.slice(fmMatch[0].length);
+    let newYaml;
+    if (/^status\s*:.*$/m.test(yamlText)) {
+        newYaml = yamlText.replace(/^status\s*:.*$/m, `status: ${status}`);
+    }
+    else {
+        newYaml = `${yamlText.replace(/\s+$/, '')}\nstatus: ${status}`;
+    }
+    const rebuilt = `---\n${newYaml}\n---\n${body}`;
+    // 自检：确认改写后能解析出目标 status，否则放弃（不落盘破坏文件）
+    const verify = parseFrontMatter(rebuilt);
+    if (!verify.isYaml || verify.status !== status)
+        return false;
+    await FileSystemUtils.writeFile(filePath, rebuilt);
+    return true;
 }
 /**
  * 全量重建 index.md 的三大分区（保留 Archive Log 既有内容）。
@@ -237,13 +456,16 @@ export function rebuildIndexContent(scan, existingContent) {
             archiveBlock = existingContent.slice(archiveIdx).trimEnd() + '\n';
         }
     }
-    // 2. 按分类整理条目（保持扫描顺序 = 字典序）
+    // 2. 拆分 active / deprecated（status===undefined 旧散文式按 active 处理）
+    const activeEntries = scan.entries.filter((e) => e.status !== 'deprecated');
+    const deprecatedEntries = scan.entries.filter((e) => e.status === 'deprecated');
+    // 3. active 条目按分类整理（保持扫描顺序 = 字典序）
     const byCategory = {
         'troubleshooting': [],
         'best-practices': [],
         'implicit-conventions': [],
     };
-    for (const e of scan.entries)
+    for (const e of activeEntries)
         byCategory[e.category].push(e);
     const parts = [INDEX_HEADER, ''];
     for (const cat of KNOWLEDGE_CATEGORIES) {
@@ -260,6 +482,20 @@ export function rebuildIndexContent(scan, existingContent) {
             parts.push('');
         }
     }
+    // 4. 失效知识折叠区（仅在存在 deprecated 条目时渲染，用 <details> 默认收起）
+    if (deprecatedEntries.length > 0) {
+        parts.push(DEPRECATED_HEADING);
+        parts.push(DEPRECATED_COMMENT);
+        parts.push('');
+        parts.push('<details>');
+        parts.push(`<summary>已失效知识 ${deprecatedEntries.length} 条（点击展开，仅作审计留痕）</summary>`);
+        parts.push('');
+        for (const e of deprecatedEntries)
+            parts.push(buildEntryLine(e));
+        parts.push('');
+        parts.push('</details>');
+        parts.push('');
+    }
     parts.push(archiveBlock.trimEnd());
     parts.push('');
     return parts.join('\n');

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

@@ -0,0 +1,61 @@
+/**
+ * Knowledge Usage Hook（引用上报）
+ *
+ * PostToolUse 旁路 hook：当 AI 通过 Read/Grep/Glob 命中 zhuanspec/knowledge/ 三类目录下的
+ * 知识文件时，往 zhuanspec/knowledge/.metrics/usage.json 累加一次「被引用」计数。
+ *
+ * 设计原则：
+ *  - 纯旁路指标，**绝不阻断主流程、绝不让 hook 非零退出**（始终 continue:true / 0 退出）。
+ *  - 仅认三类 category 子目录直属 `.md`，排除 `.pending/`、`.metrics/` 等非正式库文件。
+ *  - 留一个清晰可复用的上报接口 reportKnowledgeRef，供 hook 与未来其它调用方共用。
+ */
+/** 单条引用计数明细 */
+interface UsageCounter {
+    refCount: number;
+    lastRefAt: string;
+}
+/** usage.json 落点结构：zhuanspec/knowledge/.metrics/usage.json */
+export interface KnowledgeUsageStats {
+    schemaVersion: 1;
+    totalRefs: number;
+    /** ProjectWiki Markdown 被引用总次数 */
+    projectWikiTotalRefs: number;
+    /** 键 = 知识条目稳定主键 id（如 bp-xxx）；仅 YAML 文件有 id */
+    byId: Record<string, UsageCounter>;
+    /** 键 = 相对 knowledge/ 的路径，如 best-practices/xxx.md */
+    byFile: Record<string, UsageCounter>;
+    /** 键 = 相对 ZhuanSpec 根的 ProjectWiki 路径，如 service/.project-wiki/project.md */
+    byProjectWikiFile: Record<string, UsageCounter>;
+    lastUpdatedAt: string;
+}
+/** 单次上报输入（清晰可复用的上报接口契约） */
+export interface KnowledgeRefEvent {
+    /** 被引用的知识文件路径（绝对或相对，函数内统一归一化） */
+    filePath: string;
+    /** 引用时间，缺省取 getBeijingTime() */
+    refAt?: string;
+}
+interface KnowledgeUsageOptions {
+    json?: boolean;
+    file?: string;
+}
+/** usage.json 绝对路径 */
+export declare function getUsagePath(knowledgeDir: string): string;
+/** 读取 usage.json，缺失/损坏均返回空结构（容错，不抛） */
+export declare function readUsageStats(knowledgeDir: string): Promise<KnowledgeUsageStats>;
+/**
+ * 清晰可复用的上报接口：累加一次引用。
+ *  - filePath 未命中 knowledge/ 三类目录 → no-op 返回 false。
+ *  - 命中则读 frontmatter 取 id（缺 id 仅按 byFile 计数），同步累加 byId / byFile / totalRefs。
+ *  - 原子写回；写失败静默吞掉（旁路指标不得阻断主流程）。
+ *
+ * @returns 是否实际累加
+ */
+export declare function reportKnowledgeRef(knowledgeDir: string, event: KnowledgeRefEvent): Promise<boolean>;
+/**
+ * PostToolUse hook 入口：从 stdin(tool_input.file_path) 或 --file 提取路径后上报。
+ * 始终输出 { continue: true } 信封并以 0 退出（旁路 hook）。
+ */
+export declare function knowledgeUsageHook(options: KnowledgeUsageOptions): Promise<void>;
+export {};
+//# sourceMappingURL=knowledge-usage.d.ts.map

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

@@ -0,0 +1,192 @@
+/**
+ * Knowledge Usage Hook（引用上报）
+ *
+ * PostToolUse 旁路 hook：当 AI 通过 Read/Grep/Glob 命中 zhuanspec/knowledge/ 三类目录下的
+ * 知识文件时，往 zhuanspec/knowledge/.metrics/usage.json 累加一次「被引用」计数。
+ *
+ * 设计原则：
+ *  - 纯旁路指标，**绝不阻断主流程、绝不让 hook 非零退出**（始终 continue:true / 0 退出）。
+ *  - 仅认三类 category 子目录直属 `.md`，排除 `.pending/`、`.metrics/` 等非正式库文件。
+ *  - 留一个清晰可复用的上报接口 reportKnowledgeRef，供 hook 与未来其它调用方共用。
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { detectHookHost, sanitizeCodexEnvelope } from '../../utils/hook-host.js';
+import { getBeijingTime, atomicWriteJson } from './record-progress.js';
+import { KNOWLEDGE_CATEGORIES, parseFrontMatter } from './knowledge-index.js';
+import { resolveZhuanSpecRoot } from '../../utils/resolve-root.js';
+/** usage.json 绝对路径 */
+export function getUsagePath(knowledgeDir) {
+    return path.join(knowledgeDir, '.metrics', 'usage.json');
+}
+/** 生成空 usage 结构 */
+function emptyUsage() {
+    return {
+        schemaVersion: 1,
+        totalRefs: 0,
+        projectWikiTotalRefs: 0,
+        byId: {},
+        byFile: {},
+        byProjectWikiFile: {},
+        lastUpdatedAt: '',
+    };
+}
+/** 读取 usage.json，缺失/损坏均返回空结构（容错，不抛） */
+export async function readUsageStats(knowledgeDir) {
+    const usagePath = getUsagePath(knowledgeDir);
+    try {
+        if (!(await FileSystemUtils.fileExists(usagePath)))
+            return emptyUsage();
+        const raw = await FileSystemUtils.readFile(usagePath);
+        const parsed = JSON.parse(raw);
+        return {
+            schemaVersion: 1,
+            totalRefs: typeof parsed.totalRefs === 'number' ? parsed.totalRefs : 0,
+            projectWikiTotalRefs: typeof parsed.projectWikiTotalRefs === 'number' ? parsed.projectWikiTotalRefs : 0,
+            byId: parsed.byId && typeof parsed.byId === 'object' ? parsed.byId : {},
+            byFile: parsed.byFile && typeof parsed.byFile === 'object' ? parsed.byFile : {},
+            byProjectWikiFile: parsed.byProjectWikiFile && typeof parsed.byProjectWikiFile === 'object'
+                ? parsed.byProjectWikiFile
+                : {},
+            lastUpdatedAt: typeof parsed.lastUpdatedAt === 'string' ? parsed.lastUpdatedAt : '',
+        };
+    }
+    catch {
+        return emptyUsage();
+    }
+}
+/**
+ * 判定 filePath 是否命中 knowledge/{三类}/*.md。
+ * 命中返回相对 knowledgeDir 的 posix 风格路径（如 best-practices/xxx.md），否则返回 null。
+ */
+function matchKnowledgeFile(knowledgeDir, filePath) {
+    const absKnowledge = path.resolve(knowledgeDir);
+    const absFile = path.resolve(filePath);
+    const rel = path.relative(absKnowledge, absFile);
+    // 越出 knowledge/ 目录
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    const segments = rel.split(path.sep);
+    // 必须形如 <category>/<file>.md（恰好两段，category 合法，文件非 . 开头且 .md 结尾）
+    if (segments.length !== 2)
+        return null;
+    const [category, file] = segments;
+    if (!KNOWLEDGE_CATEGORIES.includes(category))
+        return null;
+    if (file.startsWith('.') || !file.endsWith('.md'))
+        return null;
+    return `${category}/${file}`;
+}
+/**
+ * 判定 filePath 是否命中当前工作区内的 ProjectWiki Markdown。
+ * 命中返回相对 repoRoot 的 posix 风格路径，否则返回 null。
+ */
+function matchProjectWikiFile(repoRoot, filePath) {
+    const absRoot = path.resolve(repoRoot);
+    const absFile = path.resolve(filePath);
+    const rel = path.relative(absRoot, absFile);
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    const segments = rel.split(path.sep);
+    if (!segments.includes('.project-wiki'))
+        return null;
+    const file = segments[segments.length - 1] ?? '';
+    if (file.startsWith('.') || !file.endsWith('.md'))
+        return null;
+    return segments.join('/');
+}
+/**
+ * 清晰可复用的上报接口：累加一次引用。
+ *  - filePath 未命中 knowledge/ 三类目录 → no-op 返回 false。
+ *  - 命中则读 frontmatter 取 id（缺 id 仅按 byFile 计数），同步累加 byId / byFile / totalRefs。
+ *  - 原子写回；写失败静默吞掉（旁路指标不得阻断主流程）。
+ *
+ * @returns 是否实际累加
+ */
+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);
+    if (!relPath && !projectWikiRelPath)
+        return false;
+    const refAt = event.refAt || getBeijingTime();
+    // 读 id（失败不影响 byFile 计数）
+    let id = '';
+    if (relPath)
+        try {
+            const abs = path.join(knowledgeDir, relPath);
+            if (await FileSystemUtils.fileExists(abs)) {
+                id = parseFrontMatter(await FileSystemUtils.readFile(abs)).id;
+            }
+        }
+        catch {
+            // 忽略读失败，id 留空
+        }
+    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]);
+            if (id)
+                usage.byId[id] = bump(usage.byId[id]);
+            usage.totalRefs += 1;
+        }
+        if (projectWikiRelPath) {
+            usage.byProjectWikiFile[projectWikiRelPath] = bump(usage.byProjectWikiFile[projectWikiRelPath]);
+            usage.projectWikiTotalRefs += 1;
+        }
+        usage.lastUpdatedAt = refAt;
+        await FileSystemUtils.createDirectory(path.dirname(getUsagePath(knowledgeDir)));
+        await atomicWriteJson(getUsagePath(knowledgeDir), usage);
+        return true;
+    }
+    catch {
+        // 写失败静默：上报是旁路指标，绝不能影响 Read 工具结果
+        return false;
+    }
+}
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => (data += chunk));
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(null));
+    });
+}
+/**
+ * PostToolUse hook 入口：从 stdin(tool_input.file_path) 或 --file 提取路径后上报。
+ * 始终输出 { continue: true } 信封并以 0 退出（旁路 hook）。
+ */
+export async function knowledgeUsageHook(options) {
+    let stdinData = {};
+    try {
+        const stdinContent = await readStdin();
+        if (stdinContent)
+            stdinData = JSON.parse(stdinContent);
+    }
+    catch {
+        // 忽略解析错误
+    }
+    const toolInput = stdinData.tool_input;
+    const filePath = toolInput?.file_path || toolInput?.path || options.file || '';
+    if (filePath) {
+        try {
+            const repoRoot = resolveZhuanSpecRoot(process.cwd());
+            const knowledgeDir = path.join(repoRoot, 'zhuanspec', 'knowledge');
+            await reportKnowledgeRef(knowledgeDir, { filePath });
+        }
+        catch {
+            // 旁路 hook 永不抛错
+        }
+    }
+    const envelope = { continue: true, hookSpecificOutput: { hookEventName: 'PostToolUse' } };
+    const payload = detectHookHost() === 'codex'
+        ? sanitizeCodexEnvelope(envelope, 'PostToolUse')
+        : envelope;
+    console.log(JSON.stringify(payload));
+}
+//# sourceMappingURL=knowledge-usage.js.map