autosnippet 3.2.15 → 3.2.17

package/dist/lib/service/skills/RecommendationPipeline.js

@@ -0,0 +1,228 @@
+/**
+ * RecommendationPipeline — 统一推荐管线
+ *
+ * 多阶段处理:
+ *   1. Recall  — 多策略并行召回候选 (Rule / AI / Vector / Popularity)
+ *   2. Score   — 综合评分 (信号强度 × 用户偏好 × 新鲜度)
+ *   3. Rank    — 排序 + 截断
+ *   4. Filter  — 去重、过滤已有 Skill、过滤频繁忽略的类别
+ *   5. Deliver — 输出最终推荐列表 + 触发 Hook
+ *
+ * 设计原则:
+ *   - 静默降级: 任何策略失败不影响其他策略
+ *   - 离线优先: 无 AI 时降级到规则召回
+ *   - 反馈闪环: 利用 FeedbackStore 调整排序权重
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+/** 最大召回超时 (ms) — 单个策略超时不阻塞整体 */
+const RECALL_TIMEOUT_MS = 15_000;
+/** 默认返回推荐数量 */
+const DEFAULT_TOP_K = 5;
+/** 生成唯一推荐 ID (不依赖外部库) */
+function generateRecommendationId() {
+    // crypto.randomUUID() — Node.js >=19 可用
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `rec_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+    }
+    // fallback
+    return `rec_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export class RecommendationPipeline {
+    #strategies = [];
+    #feedbackStore;
+    #skillHooks;
+    #logger;
+    constructor(opts = {}) {
+        this.#feedbackStore = opts.feedbackStore ?? null;
+        this.#skillHooks = opts.skillHooks ?? null;
+        this.#logger = Logger.getInstance();
+    }
+    // ─── 策略管理 ──────────────────────────────────────────
+    /** 注册召回策略 */
+    addStrategy(strategy) {
+        this.#strategies.push(strategy);
+        this.#logger.debug(`RecommendationPipeline: strategy "${strategy.name}" registered`);
+    }
+    /** 获取已注册策略列表 */
+    getStrategies() {
+        return this.#strategies;
+    }
+    // ─── 主管线 ────────────────────────────────────────────
+    /**
+     * 执行推荐管线
+     *
+     * @param context 推荐上下文
+     * @param topK 最多返回数量
+     * @returns 排序后的推荐结果列表
+     */
+    async recommend(context, topK = DEFAULT_TOP_K) {
+        // 注入用户偏好
+        if (this.#feedbackStore && !context.userPreference) {
+            context.userPreference = this.#feedbackStore.getUserPreference();
+        }
+        // ── 1. Recall: 多策略并行召回 ──
+        const rawCandidates = await this.#recall(context);
+        if (rawCandidates.length === 0) {
+            return [];
+        }
+        // ── 2. Score: 综合评分 ──
+        const scored = this.#score(rawCandidates, context);
+        // ── 3. Rank: 排序 ──
+        scored.sort((a, b) => b.score - a.score);
+        // ── 4. Filter: 去重 + 过滤 ──
+        const filtered = this.#filter(scored, context);
+        // ── 5. Truncate + Deliver ──
+        const results = filtered.slice(0, topK);
+        // 触发 onRecommendation hook (waterfall: 允许 hook 修改结果)
+        if (this.#skillHooks?.has('onRecommendation')) {
+            try {
+                const modified = await this.#skillHooks.run('onRecommendation', results, context);
+                if (Array.isArray(modified)) {
+                    return modified;
+                }
+            }
+            catch (err) {
+                this.#logger.warn('RecommendationPipeline: onRecommendation hook error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return results;
+    }
+    // ─── 阶段 1: 召回 ─────────────────────────────────────
+    async #recall(context) {
+        const availableStrategies = this.#strategies.filter((s) => {
+            try {
+                return s.isAvailable(context);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (availableStrategies.length === 0) {
+            this.#logger.warn('RecommendationPipeline: no available recall strategies');
+            return [];
+        }
+        // 并行召回 — 每个策略独立超时
+        const results = await Promise.allSettled(availableStrategies.map((strategy) => this.#recallWithTimeout(strategy, context)));
+        const candidates = [];
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            if (r.status === 'fulfilled') {
+                candidates.push(...r.value);
+                this.#logger.debug(`RecommendationPipeline: "${availableStrategies[i].name}" recalled ${r.value.length} candidates`);
+            }
+            else {
+                this.#logger.warn(`RecommendationPipeline: "${availableStrategies[i].name}" failed`, {
+                    error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+                });
+            }
+        }
+        return candidates;
+    }
+    async #recallWithTimeout(strategy, context) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Strategy "${strategy.name}" timed out after ${RECALL_TIMEOUT_MS}ms`));
+            }, RECALL_TIMEOUT_MS);
+            strategy
+                .recall(context)
+                .then((results) => {
+                clearTimeout(timer);
+                resolve(results);
+            })
+                .catch((err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    // ─── 阶段 2: 评分 ─────────────────────────────────────
+    #score(candidates, context) {
+        const preference = context.userPreference;
+        return candidates.map((c) => {
+            const signalScores = {};
+            // 基础优先级分
+            signalScores.priority = c.priority === 'high' ? 0.9 : c.priority === 'medium' ? 0.6 : 0.3;
+            // 来源可信度分
+            signalScores.sourceConfidence = this.#getSourceConfidence(c.source);
+            // 用户偏好匹配分
+            signalScores.userAffinity = this.#getUserAffinityScore(c, preference);
+            // 综合得分: 加权平均
+            const weights = { priority: 0.4, sourceConfidence: 0.3, userAffinity: 0.3 };
+            const score = signalScores.priority * weights.priority +
+                signalScores.sourceConfidence * weights.sourceConfidence +
+                signalScores.userAffinity * weights.userAffinity;
+            return {
+                ...c,
+                score: Math.max(0, Math.min(score, 1)),
+                signalScores,
+                recommendationId: generateRecommendationId(),
+                generatedAt: new Date().toISOString(),
+            };
+        });
+    }
+    #getSourceConfidence(source) {
+        if (source.startsWith('ai:')) {
+            return 0.8;
+        }
+        if (source.startsWith('rule:')) {
+            return 0.7;
+        }
+        if (source.startsWith('vector:')) {
+            return 0.6;
+        }
+        return 0.5;
+    }
+    #getUserAffinityScore(candidate, preference) {
+        if (!preference) {
+            return 0.5; // 无偏好数据，中性分
+        }
+        let score = 0.5;
+        // 来源偏好加分
+        const sourceType = candidate.source.split(':')[1] ?? candidate.source;
+        if (preference.preferredSources.includes(sourceType)) {
+            score += 0.2;
+        }
+        // 避开类别降分 (通过 signals 中可能包含的 category 信息)
+        const category = candidate.signals.category;
+        if (category) {
+            if (preference.preferredCategories.includes(category)) {
+                score += 0.2;
+            }
+            if (preference.avoidedCategories.includes(category)) {
+                score -= 0.3;
+            }
+        }
+        return Math.max(0, Math.min(score, 1));
+    }
+    // ─── 阶段 3: 过滤 ─────────────────────────────────────
+    #filter(scored, context) {
+        const existingSet = context.existingSkills ?? new Set();
+        const seen = new Set();
+        const results = [];
+        for (const rec of scored) {
+            // 去重 (同名)
+            if (seen.has(rec.name)) {
+                continue;
+            }
+            // 已有 Skill 过滤
+            if (existingSet.has(rec.name)) {
+                continue;
+            }
+            // 频繁忽略的类别过滤
+            const category = rec.signals.category;
+            if (category && this.#feedbackStore?.isFrequentlyDismissed(category)) {
+                continue;
+            }
+            // 低分过滤 (得分 < 0.2 的推荐丢弃)
+            if (rec.score < 0.2) {
+                continue;
+            }
+            seen.add(rec.name);
+            results.push(rec);
+        }
+        return results;
+    }
+}
+export default RecommendationPipeline;

package/dist/lib/service/skills/RuleRecallStrategy.d.ts

@@ -0,0 +1,15 @@
+/**
+ * RuleRecallStrategy — 将 SkillAdvisor 包装为 RecallStrategy 接口
+ *
+ * 零 AI 依赖、零延迟，作为离线 fallback 和基础召回来源。
+ * 复用 SkillAdvisor 的 4 维分析（Guard 违规、Memory 偏好、Recipe 分布、候选积压），
+ * 将 SkillSuggestion 转换为标准 RecommendationCandidate。
+ */
+import type { RecallStrategy, RecommendationCandidate, RecommendationContext } from './types.js';
+export declare class RuleRecallStrategy implements RecallStrategy {
+    readonly name = "rule";
+    readonly type: "rule";
+    recall(context: RecommendationContext): Promise<RecommendationCandidate[]>;
+    isAvailable(_context: RecommendationContext): boolean;
+}
+export default RuleRecallStrategy;

package/dist/lib/service/skills/RuleRecallStrategy.js

@@ -0,0 +1,36 @@
+/**
+ * RuleRecallStrategy — 将 SkillAdvisor 包装为 RecallStrategy 接口
+ *
+ * 零 AI 依赖、零延迟，作为离线 fallback 和基础召回来源。
+ * 复用 SkillAdvisor 的 4 维分析（Guard 违规、Memory 偏好、Recipe 分布、候选积压），
+ * 将 SkillSuggestion 转换为标准 RecommendationCandidate。
+ */
+import { SkillAdvisor } from './SkillAdvisor.js';
+export class RuleRecallStrategy {
+    name = 'rule';
+    type = 'rule';
+    async recall(context) {
+        const db = context.database;
+        const advisor = new SkillAdvisor(context.projectRoot, {
+            database: db,
+        });
+        const result = advisor.suggest();
+        // 过滤已有 Skill
+        const existingSet = context.existingSkills ?? new Set();
+        return result.suggestions
+            .filter((s) => !existingSet.has(s.name))
+            .map((s) => ({
+            name: s.name,
+            description: s.description,
+            rationale: s.rationale,
+            source: `rule:${s.source}`,
+            priority: s.priority,
+            signals: s.signals,
+        }));
+    }
+    isAvailable(_context) {
+        // 规则召回始终可用
+        return true;
+    }
+}
+export default RuleRecallStrategy;

package/dist/lib/service/skills/SignalCollector.d.ts

@@ -76,14 +76,13 @@ interface ContainerLike {
 export declare class SignalCollector {
     #private;
     /**
-     * @param {object} opts
-     * @param {string} opts.projectRoot  用户项目根目录
-     * @param {object} [opts.database]   - better-sqlite3 实例
-     * @param {object} [opts.agentFactory] - AgentFactory 实例
-     * @param {object} [opts.container]  - ServiceContainer 实例
-     * @param {string} [opts.mode]       - 'off' | 'suggest' | 'auto'
-     * @param {number} [opts.intervalMs] 初始收集间隔（毫秒），后续由 AI 动态调整
-     * @param {function} [opts.onSuggestions] 新建议回调 (suggestions[]) => void
+     * @param opts.projectRoot 用户项目根目录
+     * @param [opts.database] better-sqlite3 实例
+     * @param [opts.agentFactory] AgentFactory 实例
+     * @param [opts.container] ServiceContainer 实例
+     * @param [opts.mode] 'off' | 'suggest' | 'auto'
+     * @param [opts.intervalMs] 初始收集间隔（毫秒），后续由 AI 动态调整
+     * @param [opts.onSuggestions] 新建议回调 (suggestions[]) => void
      */
     constructor({ projectRoot, database, agentFactory, container, mode, intervalMs, onSuggestions, }: SignalCollectorOpts);
     start(): void;
@@ -92,16 +91,16 @@ export declare class SignalCollector {
      * 外部事件推送入口（由 FileWatcher / Guard / CLI 等调用）
      *
      * 事件会经过 EventAggregator 聚合后触发提前分析。
-     * @param {string} key 事件类型（如 'file_change', 'guard_violation', 'candidate_submit'）
-     * @param {object} event 事件数据
+     * @param key 事件类型（如 'file_change', 'guard_violation', 'candidate_submit'）
+     * @param event 事件数据
      */
     pushEvent(key: string, event: Record<string, unknown>): void;
     collect(): Promise<{
+        suggestions: Record<string, unknown>[];
+        stats: Record<string, unknown> | null;
+    } | {
         suggestions: any;
         stats: Record<string, unknown>;
-    } | {
-        suggestions: never[];
-        stats: null;
     } | null>;
     getSnapshot(): {
         lastRun: string | null;
@@ -122,4 +121,3 @@ export declare class SignalCollector {
     resetPushed(): void;
 }
 export default SignalCollector;
-//# sourceMappingURL=SignalCollector.d.ts.map

package/dist/lib/service/skills/SignalCollector.js

@@ -42,6 +42,7 @@ import path from 'node:path';
 import Logger from '../../infrastructure/logging/Logger.js';
 import pathGuard from '../../shared/PathGuard.js';
 import { EventAggregator } from './EventAggregator.js';
+import { SkillAdvisor } from './SkillAdvisor.js';
 const DEFAULT_INTERVAL_MS = 60 * 60 * 1000; // 1 小时（初始值，AI 可动态调整）
 const MIN_INTERVAL_MS = 5 * 60 * 1000; // 最短 5 分钟
 const MAX_INTERVAL_MS = 24 * 60 * 60 * 1000; // 最长 24 小时
@@ -62,14 +63,13 @@ export class SignalCollector {
     /** @type {EventAggregator} 信号聚类引擎 */
     #aggregator;
     /**
-     * @param {object} opts
-     * @param {string} opts.projectRoot  用户项目根目录
-     * @param {object} [opts.database]   - better-sqlite3 实例
-     * @param {object} [opts.agentFactory] - AgentFactory 实例
-     * @param {object} [opts.container]  - ServiceContainer 实例
-     * @param {string} [opts.mode]       - 'off' | 'suggest' | 'auto'
-     * @param {number} [opts.intervalMs] 初始收集间隔（毫秒），后续由 AI 动态调整
-     * @param {function} [opts.onSuggestions] 新建议回调 (suggestions[]) => void
+     * @param opts.projectRoot 用户项目根目录
+     * @param [opts.database] better-sqlite3 实例
+     * @param [opts.agentFactory] AgentFactory 实例
+     * @param [opts.container] ServiceContainer 实例
+     * @param [opts.mode] 'off' | 'suggest' | 'auto'
+     * @param [opts.intervalMs] 初始收集间隔（毫秒），后续由 AI 动态调整
+     * @param [opts.onSuggestions] 新建议回调 (suggestions[]) => void
      */
     constructor({ projectRoot, database = null, agentFactory = null, container = null, mode = 'auto', intervalMs = DEFAULT_INTERVAL_MS, onSuggestions = null, }) {
         this.#projectRoot = projectRoot;
@@ -105,8 +105,7 @@ export class SignalCollector {
         }
         const aiProvider = this.#container?.get('aiProvider');
         if (!aiProvider || aiProvider.name === 'mock') {
-            this.#logger.info('[SignalCollector] no AI provider available, skipping start');
-            return;
+            this.#logger.info('[SignalCollector] no AI provider available, starting in rule-fallback mode');
         }
         if (this.#timer) {
             this.#logger.warn('[SignalCollector] already running, ignoring start()');
@@ -130,8 +129,8 @@ export class SignalCollector {
      * 外部事件推送入口（由 FileWatcher / Guard / CLI 等调用）
      *
      * 事件会经过 EventAggregator 聚合后触发提前分析。
-     * @param {string} key 事件类型（如 'file_change', 'guard_violation', 'candidate_submit'）
-     * @param {object} event 事件数据
+     * @param key 事件类型（如 'file_change', 'guard_violation', 'candidate_submit'）
+     * @param event 事件数据
      */
     pushEvent(key, event) {
         if (this.#mode === 'off') {
@@ -187,12 +186,18 @@ export class SignalCollector {
                 actions: this.#collectRecentActions(),
                 codeChanges: this.#collectCodeChangeSignals(),
             };
+            // ── 离线 Fallback: 当 AI 不可用时，降级到 SkillAdvisor 规则引擎 ──
+            const aiProvider = this.#container?.get('aiProvider');
+            if (!this.#agentFactory || !aiProvider || aiProvider.name === 'mock') {
+                this.#logger.info('[SignalCollector] AI unavailable, falling back to rule-based analysis');
+                return this.#ruleFallback();
+            }
             // 2. 构造分析 prompt
             const prompt = this.#buildAnalysisPrompt(signals);
             // 3. 调用 Agent 系统进行 AI 分析
             this.#logger.debug('[SignalCollector] invoking Agent for analysis...');
             const agent = this.#agentFactory.createChat({ lang: 'en' });
-            const { AgentMessage } = await import('../agent/AgentMessage.js');
+            const { AgentMessage } = await import('#agent/AgentMessage.js');
             const message = AgentMessage.internal(prompt, { source: 'signal_collector' });
             const result = await agent.execute(message);
             const reply = result?.reply ?? result?.text ?? '';
@@ -287,6 +292,70 @@ export class SignalCollector {
         this.#timer = setTimeout(() => this.#tick(), delayMs);
     }
     // ═══════════════════════════════════════════════════════
+    //  离线 Fallback — 无 AI 时降级到规则引擎
+    // ═══════════════════════════════════════════════════════
+    /**
+     * 当 AI Provider 不可用时，使用 SkillAdvisor 规则引擎生成推荐
+     *
+     * 零延迟、零 token 消耗 — 确保推荐系统始终有输出
+     */
+    #ruleFallback() {
+        try {
+            const advisor = new SkillAdvisor(this.#projectRoot, { database: this.#db });
+            const result = advisor.suggest();
+            const newSuggestions = result.suggestions.filter((s) => !this.#snapshot.pushedNames.includes(s.name));
+            // 更新快照
+            this.#snapshot.lastRun = new Date().toISOString();
+            this.#snapshot.totalRuns = (this.#snapshot.totalRuns || 0) + 1;
+            this.#snapshot.lastAiSummary = '[offline] Rule-based analysis (AI unavailable)';
+            this.#snapshot.lastResult = {
+                totalSuggestions: result.suggestions.length,
+                newSuggestions: newSuggestions.length,
+                aiToolCalls: 0,
+                fallback: true,
+            };
+            if (newSuggestions.length > 0) {
+                this.#snapshot.pendingSuggestions = newSuggestions.map((s) => ({
+                    name: s.name,
+                    description: s.description,
+                    rationale: s.rationale,
+                    body: '',
+                    source: `rule-fallback:${s.source}`,
+                    priority: s.priority,
+                }));
+                for (const s of newSuggestions) {
+                    if (!this.#snapshot.pushedNames.includes(s.name)) {
+                        this.#snapshot.pushedNames.push(s.name);
+                    }
+                }
+                if (this.#onSuggestions) {
+                    try {
+                        this.#onSuggestions(newSuggestions);
+                    }
+                    catch (err) {
+                        this.#logger.warn(`[SignalCollector] onSuggestions callback error (fallback): ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                this.#logger.info(`[SignalCollector] rule fallback done — ${newSuggestions.length} new suggestions`);
+            }
+            this.#saveSnapshot();
+            // 离线模式使用较长间隔（减少无意义的重复分析）
+            this.#scheduleNext(Math.min(this.#intervalMs * 2, MAX_INTERVAL_MS));
+            return {
+                suggestions: newSuggestions,
+                stats: this.#snapshot.lastResult,
+            };
+        }
+        catch (err) {
+            this.#logger.warn(`[SignalCollector] rule fallback error: ${err instanceof Error ? err.message : String(err)}`);
+            this.#scheduleNext(Math.min(this.#intervalMs * 2, MAX_INTERVAL_MS));
+            return { suggestions: [], stats: null };
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+    // ═══════════════════════════════════════════════════════
     //  信号收集器（6 维度）
     // ═══════════════════════════════════════════════════════
     #collectGuardSignals() {
@@ -468,8 +537,8 @@ ${JSON.stringify(signals.codeChanges, null, 2)}
      *   1. AiProvider.extractJSON (支持 markdown 清理、截断修复、trailing comma 等)
      *   2. 最后一行 JSON 回退 (兼容 prompt 要求的 "最后一行输出 JSON" 格式)
      *
-     * @param {string} reply - AgentRuntime.execute() 的回复文本
-     * @returns {{ suggestions: Array, nextIntervalMinutes: number|null, summary: string }}
+     * @param reply AgentRuntime.execute() 的回复文本
+     * @returns }
      */
     #parseStructuredReply(reply) {
         const defaultResult = { suggestions: [], nextIntervalMinutes: null, summary: '' };
@@ -572,4 +641,3 @@ ${JSON.stringify(signals.codeChanges, null, 2)}
     }
 }
 export default SignalCollector;
-//# sourceMappingURL=SignalCollector.js.map

package/dist/lib/service/skills/SkillAdvisor.d.ts

@@ -33,9 +33,8 @@ interface SkillAdvisorOpts {
 export declare class SkillAdvisor {
     #private;
     /**
-     * @param {string} projectRoot 用户项目根目录
-     * @param {object} [opts]
-     * @param {object} [opts.database] - better-sqlite3 实例（可选）
+     * @param projectRoot 用户项目根目录
+     * @param [opts.database] better-sqlite3 实例（可选）
      */
     constructor(projectRoot: string, { database }?: SkillAdvisorOpts);
     /**
@@ -61,4 +60,3 @@ export declare class SkillAdvisor {
     };
 }
 export default SkillAdvisor;
-//# sourceMappingURL=SkillAdvisor.d.ts.map

package/dist/lib/service/skills/SkillAdvisor.js

@@ -21,9 +21,8 @@ export class SkillAdvisor {
     #projectRoot;
     #db;
     /**
-     * @param {string} projectRoot 用户项目根目录
-     * @param {object} [opts]
-     * @param {object} [opts.database] - better-sqlite3 实例（可选）
+     * @param projectRoot 用户项目根目录
+     * @param [opts.database] better-sqlite3 实例（可选）
      */
     constructor(projectRoot, { database } = {}) {
         this.#projectRoot = projectRoot;
@@ -305,9 +304,7 @@ export class SkillAdvisor {
     // ═══════════════════════════════════════════════════════
     //  辅助方法
     // ═══════════════════════════════════════════════════════
-    /**
-     * 列出已有的项目级 Skill 名称集合（避免重复推荐）
-     */
+    /** 列出已有的项目级 Skill 名称集合（避免重复推荐） */
     #listExistingProjectSkills() {
         const names = new Set();
         const dir = getProjectSkillsPath(this.#projectRoot);
@@ -324,9 +321,7 @@ export class SkillAdvisor {
         return names;
     }
 }
-/**
- * 字符串转 kebab-case（简化版）
- */
+/** 字符串转 kebab-case（简化版） */
 function _kebab(str) {
     return (str || 'unknown')
         .replace(/[^a-zA-Z0-9\s-]/g, '')
@@ -335,4 +330,3 @@ function _kebab(str) {
         .substring(0, 30);
 }
 export default SkillAdvisor;
-//# sourceMappingURL=SkillAdvisor.js.map

package/dist/lib/service/skills/SkillHooks.d.ts

@@ -1,22 +1,23 @@
 /**
- * SkillHooks — Skill 生命周期钩子管理器
+ * SkillHooks — Skill 生命周期钩子管理器 (v2)
  *
  * 每个 Skill 目录可以包含一个 hooks.js 文件，导出生命周期回调。
- * SkillHooks 在启动时扫描并注册所有钩子，在特定事件发生时按序调用。
+ * SkillHooks 在启动时扫描并注册所有钩子，在特定事件发生时按模式调用。
  *
- * 支持的钩子:
- *   - onCandidateSubmit(candidate, ctx) → { block?: boolean, reason?: string }
- *   - onRecipeCreated(recipe, ctx) → void
- *   - onGuardCheck(violation, ctx) → violation (可修改)
- *   - onBootstrapComplete(stats, ctx) → void
+ * v2 升级:
+ *   - 扩展到 16+ 钩子，覆盖知识/Guard/Skill/搜索/推荐/Bootstrap/信号全生命周期
+ *   - 4 种执行模式: series / parallel / waterfall / bail
+ *   - Handler 支持 priority、timeout、name 元数据
+ *   - 完全向后兼容旧版 hooks.js (直接导出函数)
+ *   - 新格式支持: export default { hooks: { onXxx: { handler, priority, timeout } } }
  *
  * 加载顺序: 内置 skills/ → 项目级 AutoSnippet/skills/（同名覆盖）
  */
 import Logger from '../../infrastructure/logging/Logger.js';
-type HookHandler = (...args: unknown[]) => Promise<unknown> | unknown;
+import type { HookDefinition, HookHandlerOptions, RegisteredHandler } from './types.js';
 export declare class SkillHooks {
     #private;
-    hooks: Map<string, HookHandler[]>;
+    hooks: Map<string, RegisteredHandler[]>;
     logger: ReturnType<typeof Logger.getInstance>;
     constructor();
     /**
@@ -28,18 +29,25 @@ export declare class SkillHooks {
             _projectRoot?: unknown;
         };
     }): Promise<void>;
+    /** 手动注册 handler (用于代码级注册，非 hooks.js) */
+    tap(hookName: string, handler: (...args: unknown[]) => Promise<unknown> | unknown, options?: Partial<HookHandlerOptions>): void;
     /**
-     * 触发钩子 — 按注册顺序调用
+     * 触发钩子 — 根据 hook 定义的模式自动选择执行策略
      *
-     * @param {string} hookName
-     * @param  {...any} args
-     * @returns {Promise<any>} 最后一个返回值（用于 blocking hooks 如 onCandidateSubmit）
+     * 向后兼容: 旧版 run() 签名不变，行为维持一致。
+     * - bail 模式: 首个返回 { block: true } 的 handler 立即终止
+     * - waterfall 模式: 前一个 handler 的返回值传给下一个
+     * - parallel 模式: 所有 handler 并行执行 (fire-and-forget)
+     * - series 模式: 按优先级顺序串行执行，忽略返回值
      */
     run(hookName: string, ...args: unknown[]): Promise<unknown>;
-    /**
-     * 检查是否有任何钩子注册
-     */
-    has(hookName: string): boolean | undefined;
+    /** 检查是否有任何钩子注册 */
+    has(hookName: string): boolean;
+    /** 获取指定 hook 的 handler 数量 */
+    count(hookName: string): number;
+    /** 获取已注册的所有 hook 名称 */
+    getRegisteredHooks(): string[];
+    /** 获取 Hook Registry 信息 (用于 Dashboard / 调试) */
+    static getHookRegistry(): ReadonlyArray<HookDefinition>;
 }
 export default SkillHooks;
-//# sourceMappingURL=SkillHooks.d.ts.map