autosnippet 3.3.5 → 3.3.7

package/dist/lib/agent/tools/index.d.ts

@@ -6,6 +6,7 @@
 import { enrichCandidate, refineBootstrapCandidates } from './ai-analysis.js';
 import { getCategoryMap, getClassHierarchy, getClassInfo, getMethodOverrides, getPreviousAnalysis, getPreviousEvidence, getProjectOverview, getProtocolInfo, noteFinding, queryCallGraph, queryCodeGraph } from './ast-graph.js';
 import { analyzeCode, getToolDetails, knowledgeOverview, planTask, reviewMyOutput, submitWithCheck } from './composite.js';
+import { confirmDeprecation, proposeEvolution, skipEvolution } from './evolution-tools.js';
 import { getRecommendations, guardCheckCode, listGuardRules, queryViolations } from './guard.js';
 import { bootstrapKnowledgeTool, createSkillTool, graphImpactAnalysis, loadSkill, queryAuditLog, rebuildIndex, suggestSkills } from './infrastructure.js';
 import { addGraphEdge, checkDuplicate } from './knowledge-graph.js';
@@ -14,76 +15,8 @@ import { getFileSummary, listProjectStructure, readProjectFile, searchProjectCod
 import { getProjectStats, getRecipeDetail, getRelatedRecipes, searchCandidates, searchKnowledge, searchRecipes } from './query.js';
 import { collectScanRecipe } from './scan-recipe.js';
 import { getEnvironmentInfo, runSafeCommand, writeProjectFile } from './system-interaction.js';
-export { searchProjectCode, readProjectFile, listProjectStructure, getFileSummary, semanticSearchCode, searchRecipes, searchCandidates, getRecipeDetail, getProjectStats, searchKnowledge, getRelatedRecipes, enrichCandidate, refineBootstrapCandidates, listGuardRules, getRecommendations, guardCheckCode, queryViolations, checkDuplicate, addGraphEdge, submitCandidate, approveCandidate, rejectCandidate, publishRecipe, deprecateRecipe, updateRecipe, recordUsage, qualityScore, validateCandidate, getFeedbackStats, graphImpactAnalysis, rebuildIndex, queryAuditLog, loadSkill, createSkillTool, suggestSkills, bootstrapKnowledgeTool, analyzeCode, knowledgeOverview, submitWithCheck, getToolDetails, planTask, reviewMyOutput, getProjectOverview, getClassHierarchy, getClassInfo, getProtocolInfo, getMethodOverrides, getCategoryMap, getPreviousAnalysis, noteFinding, getPreviousEvidence, queryCodeGraph, queryCallGraph, collectScanRecipe, runSafeCommand, writeProjectFile, getEnvironmentInfo, };
+export { searchProjectCode, readProjectFile, listProjectStructure, getFileSummary, semanticSearchCode, searchRecipes, searchCandidates, getRecipeDetail, getProjectStats, searchKnowledge, getRelatedRecipes, enrichCandidate, refineBootstrapCandidates, listGuardRules, getRecommendations, guardCheckCode, queryViolations, checkDuplicate, addGraphEdge, submitCandidate, approveCandidate, rejectCandidate, publishRecipe, deprecateRecipe, updateRecipe, recordUsage, qualityScore, validateCandidate, getFeedbackStats, graphImpactAnalysis, rebuildIndex, queryAuditLog, loadSkill, createSkillTool, suggestSkills, bootstrapKnowledgeTool, analyzeCode, knowledgeOverview, submitWithCheck, getToolDetails, planTask, reviewMyOutput, getProjectOverview, getClassHierarchy, getClassInfo, getProtocolInfo, getMethodOverrides, getCategoryMap, getPreviousAnalysis, noteFinding, getPreviousEvidence, queryCodeGraph, queryCallGraph, collectScanRecipe, runSafeCommand, writeProjectFile, getEnvironmentInfo, proposeEvolution, confirmDeprecation, skipEvolution, };
 export declare const ALL_TOOLS: ({
-    name: string;
-    description: string;
-    parameters: {
-        type: string;
-        properties: {
-            candidateIds: {
-                type: string;
-                items: {
-                    type: string;
-                };
-                description: string;
-            };
-        };
-        required: string[];
-    };
-    handler: (params: Record<string, unknown>, ctx: import("./_shared.js").ToolHandlerContext) => Promise<{
-        total: number;
-        needsEnrichment: number;
-        needsRecipeFields: number;
-        fullyComplete: number;
-        entries: import("../../external/mcp/handlers/types.js").EnrichResultEntry[];
-        hint: string;
-    } | {
-        success: boolean;
-        errorCode: string | null;
-        message: string;
-        data: {
-            total: number;
-            needsEnrichment: number;
-            needsRecipeFields: number;
-            fullyComplete: number;
-            entries: import("../../external/mcp/handlers/types.js").EnrichResultEntry[];
-            hint: string;
-        } | null;
-        meta: {
-            source?: string | undefined;
-            responseTimeMs?: number | undefined;
-            version: string;
-            tool?: string | undefined;
-        };
-    } | {
-        error: string;
-    }>;
-} | {
-    name: string;
-    description: string;
-    parameters: {
-        type: string;
-        properties: {
-            candidateIds: {
-                type: string;
-                items: {
-                    type: string;
-                };
-                description: string;
-            };
-            userPrompt: {
-                type: string;
-                description: string;
-            };
-            dryRun: {
-                type: string;
-                description: string;
-            };
-        };
-    };
-    handler: (params: Record<string, unknown>, ctx: import("./_shared.js").ToolHandlerContext) => Promise<{}>;
-} | {
     name: string;
     description: string;
     parameters: {
@@ -397,13 +330,14 @@ export declare const ALL_TOOLS: ({
                 type: string;
                 description: string;
             };
+            supersedes: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };
     handler: (params: import("./composite.js").SubmitWithCheckParams, ctx: import("./_shared.js").ToolHandlerContext) => Promise<{
-        status: string;
-        reason: string;
-    } | {
         submitted: boolean;
         status: string;
         reason: string;
@@ -413,10 +347,19 @@ export declare const ALL_TOOLS: ({
             confidence: string;
             hint: string;
         };
+        error?: undefined;
+        similar?: undefined;
+        highestSimilarity?: undefined;
+    } | {
+        submitted: boolean;
+        reason: string;
+        error: string;
+        status?: undefined;
+        errors?: undefined;
+        warnings?: undefined;
+        _meta?: undefined;
         similar?: undefined;
         highestSimilarity?: undefined;
-        entry?: undefined;
-        error?: undefined;
     } | {
         submitted: boolean;
         reason: string;
@@ -433,37 +376,28 @@ export declare const ALL_TOOLS: ({
         status?: undefined;
         errors?: undefined;
         warnings?: undefined;
-        entry?: undefined;
         error?: undefined;
     } | {
+        _meta: {
+            confidence: string;
+            hint: string;
+        };
+        _supersedeProposal?: {
+            proposalId: string;
+        } | undefined;
         submitted: boolean;
-        entry: any;
+        entry: unknown;
         similar: {
             file: string;
             title: string;
             similarity: number;
         }[];
-        _meta: {
-            confidence: string;
-            hint: string;
-        };
         status?: undefined;
         reason?: undefined;
         errors?: undefined;
         warnings?: undefined;
-        highestSimilarity?: undefined;
         error?: undefined;
-    } | {
-        submitted: boolean;
-        reason: string;
-        error: string;
-        status?: undefined;
-        errors?: undefined;
-        warnings?: undefined;
-        _meta?: undefined;
-        similar?: undefined;
         highestSimilarity?: undefined;
-        entry?: undefined;
     }>;
 } | {
     name: string;
@@ -592,6 +526,71 @@ export declare const ALL_TOOLS: ({
         }[];
         message: string;
     }>;
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            recipeId: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            evidence: {
+                type: string;
+                description: string;
+                properties: {
+                    sourceStatus: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    currentCode: {
+                        type: string;
+                        description: string;
+                    };
+                    newLocation: {
+                        type: string;
+                        description: string;
+                    };
+                    suggestedChanges: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
+            confidence: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: import("./evolution-tools.js").ProposeEvolutionParams, ctx: import("./_shared.js").ToolHandlerContext) => Promise<{
+        status: "error";
+        message: string;
+        recipeId: string;
+        proposalId?: undefined;
+        type?: undefined;
+        expiresAt?: undefined;
+    } | {
+        status: "proposed";
+        proposalId: string;
+        recipeId: string;
+        type: "enhance" | "correction";
+        expiresAt: number;
+        message?: undefined;
+    }>;
 } | {
     name: string;
     description: string;
@@ -1024,10 +1023,14 @@ export declare const ALL_TOOLS: ({
                 type: string;
                 description: string;
             };
+            supersedes: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };
-    handler: (params: import("./lifecycle.js").SubmitKnowledgeParams, ctx: import("./_shared.js").ToolHandlerContext) => Promise<any>;
+    handler: (params: import("./lifecycle.js").SubmitKnowledgeParams, ctx: import("./_shared.js").ToolHandlerContext) => Promise<Record<string, unknown>>;
 } | {
     name: string;
     description: string;
@@ -1850,5 +1853,73 @@ export declare const ALL_TOOLS: ({
         required: never[];
     };
     handler: (params: import("./system-interaction.js").GetEnvironmentInfoParams, ctx: import("./_shared.js").ToolHandlerContext) => Promise<import("./system-interaction.js").EnvironmentInfo>;
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            candidateIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: Record<string, unknown>, ctx: import("./_shared.js").ToolHandlerContext) => Promise<{
+        total: number;
+        needsEnrichment: number;
+        needsRecipeFields: number;
+        fullyComplete: number;
+        entries: import("../../external/mcp/handlers/types.js").EnrichResultEntry[];
+        hint: string;
+    } | {
+        success: boolean;
+        errorCode: string | null;
+        message: string;
+        data: {
+            total: number;
+            needsEnrichment: number;
+            needsRecipeFields: number;
+            fullyComplete: number;
+            entries: import("../../external/mcp/handlers/types.js").EnrichResultEntry[];
+            hint: string;
+        } | null;
+        meta: {
+            source?: string | undefined;
+            responseTimeMs?: number | undefined;
+            version: string;
+            tool?: string | undefined;
+        };
+    } | {
+        error: string;
+    }>;
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            candidateIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            userPrompt: {
+                type: string;
+                description: string;
+            };
+            dryRun: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+    handler: (params: Record<string, unknown>, ctx: import("./_shared.js").ToolHandlerContext) => Promise<{}>;
 })[];
 export default ALL_TOOLS;

package/dist/lib/agent/tools/index.js

@@ -9,6 +9,8 @@ import { enrichCandidate, refineBootstrapCandidates } from './ai-analysis.js';
 import { getCategoryMap, getClassHierarchy, getClassInfo, getMethodOverrides, getPreviousAnalysis, getPreviousEvidence, getProjectOverview, getProtocolInfo, noteFinding, queryCallGraph, queryCodeGraph, } from './ast-graph.js';
 // ── 组合工具 + 元工具 (6) ──
 import { analyzeCode, getToolDetails, knowledgeOverview, planTask, reviewMyOutput, submitWithCheck, } from './composite.js';
+// ── Evolution Agent 工具 (3) ──
+import { confirmDeprecation, proposeEvolution, skipEvolution } from './evolution-tools.js';
 // ── Guard 安全类 (4) ──
 import { getRecommendations, guardCheckCode, listGuardRules, queryViolations } from './guard.js';
 // ── 基础设施类 (7) ──
@@ -54,7 +56,9 @@ queryCallGraph,
 // 扫描 Recipe 收集
 collectScanRecipe, 
 // 系统交互类
-runSafeCommand, writeProjectFile, getEnvironmentInfo, };
+runSafeCommand, writeProjectFile, getEnvironmentInfo, 
+// Evolution Agent 工具
+proposeEvolution, confirmDeprecation, skipEvolution, };
 // ── ALL_TOOLS 数组（与原始 tools.js 顺序一致）──
 export const ALL_TOOLS = [
     // 项目数据访问 (5) — 含 v10 Agent-Pull 工具
@@ -131,5 +135,9 @@ export const ALL_TOOLS = [
     getEnvironmentInfo,
     // 扫描 Recipe 收集 (1) — scanKnowledge produce 阶段专用
     collectScanRecipe,
+    // Evolution Agent 工具 (3) — 提案驱动的 Recipe 进化决策
+    proposeEvolution,
+    confirmDeprecation,
+    skipEvolution,
 ];
 export default ALL_TOOLS;

package/dist/lib/agent/tools/lifecycle.d.ts

@@ -42,6 +42,8 @@ export interface SubmitKnowledgeParams {
     usageGuide?: string;
     sourceFile?: string;
     _category?: string;
+    /** 被替代的旧 Recipe ID（进化架构入口） */
+    supersedes?: string;
     [key: string]: unknown;
 }
 export declare const submitCandidate: {
@@ -132,10 +134,14 @@ export declare const submitCandidate: {
                 type: string;
                 description: string;
             };
+            supersedes: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };
-    handler: (params: SubmitKnowledgeParams, ctx: ToolHandlerContext) => Promise<any>;
+    handler: (params: SubmitKnowledgeParams, ctx: ToolHandlerContext) => Promise<Record<string, unknown>>;
 };
 export declare const approveCandidate: {
     name: string;

package/dist/lib/agent/tools/lifecycle.js

@@ -13,8 +13,7 @@
  * 25.  get_feedback_stats   反馈统计
  */
 import { getInternalAgentRequiredFields, getSystemInjectedFields, } from '#domain/knowledge/FieldSpec.js';
-import { UnifiedValidator } from '#domain/knowledge/UnifiedValidator.js';
-import { checkDimensionType, DIMENSION_DISPLAY_GROUP } from './_shared.js';
+import { checkDimensionType, DIMENSION_DISPLAY_GROUP, stripProjectNamePrefix, } from './_shared.js';
 // ────────────────────────────────────────────────────────────
 // 16. submit_knowledge
 // ────────────────────────────────────────────────────────────
@@ -71,14 +70,24 @@ export const submitCandidate = {
                 description: '知识维度：code-pattern / architecture / best-practice 等',
             },
             usageGuide: { type: 'string', description: '使用指南 Markdown（### 章节格式）' },
-            sourceFile: { type: 'string', description: '来源文件相对路径' },
+            sourceFile: {
+                type: 'string',
+                description: 'Recipe md 文件相对路径（由系统自动设置，无需手动填写）',
+            },
+            supersedes: {
+                type: 'string',
+                description: '被替代的旧 Recipe ID。传入后将创建 supersede 提案，72h 观察窗口后自动替代。',
+            },
         },
         // FieldSpec 驱动: 内部 Agent 路径排除系统注入字段
         required: getInternalAgentRequiredFields(),
     },
     handler: async (params, ctx) => {
-        const knowledgeService = ctx.container.get('knowledgeService');
-        // ── Bootstrap 维度类型校验 ──
+        // ── 标题正规化：剥离冗余的项目名前缀 ──
+        if (params.title) {
+            params.title = stripProjectNamePrefix(params.title, ctx.projectRoot);
+        }
+        // ── Bootstrap 维度类型校验（source-specific: 仅 bootstrap 流程） ──
         const dimMeta = ctx._dimensionMeta;
         if (dimMeta && ctx.source === 'system') {
             const rejected = checkDimensionType(dimMeta, params, ctx.logger);
@@ -95,89 +104,64 @@ export const submitCandidate = {
             if (!params.tags.includes('bootstrap')) {
                 params.tags.push('bootstrap');
             }
-            // Bootstrap 模式: 将 category 覆盖为展示分组 ID
-            params._category =
-                DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
-            // ── UnifiedValidator 统一质量验证（替代 CandidateGuardrail） ──
-            const validator = ctx._validator ||
-                new UnifiedValidator({
-                    existingTitles: ctx._submittedTitles || new Set(),
-                    existingFingerprints: ctx._submittedPatterns || new Set(),
-                });
-            const validResult = validator.validate(params, {
-                systemInjectedFields: getSystemInjectedFields(),
-            });
-            if (!validResult.pass) {
-                ctx.logger?.info(`[submit_knowledge] ✗ validator rejected: ${validResult.errors.join('; ')}`);
-                return {
-                    status: 'rejected',
-                    error: validResult.errors.join('\n'),
-                    warnings: validResult.warnings,
-                    hint: '请根据错误信息调整内容后重新提交。',
-                };
-            }
-            if (validResult.warnings.length > 0) {
-                ctx.logger?.debug(`[submit_knowledge] ⚠ warnings: ${validResult.warnings.join('; ')}`);
-            }
+            // Bootstrap 模式: 将 category 设为维度 ID（前端按此分组显示）
+            params._category = dimMeta.id;
         }
         // ── 系统自动设置 ──
-        const systemFields = {
+        const item = {
+            ...params,
             language: ctx._projectLanguage || '',
-            category: dimMeta
-                ? DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id
-                : 'general',
-            knowledgeType: dimMeta?.allowedKnowledgeTypes?.[0] || 'code-pattern',
+            category: dimMeta ? dimMeta.id : params._category || 'general',
+            knowledgeType: dimMeta?.allowedKnowledgeTypes?.[0] || params.knowledgeType || 'code-pattern',
             source: ctx.source === 'system' ? 'bootstrap' : 'agent',
-        };
-        // ── 直传 → KnowledgeEntry ──
-        const reasoning = params.reasoning || { whyStandard: '', sources: ['agent'], confidence: 0.7 };
-        if (Array.isArray(reasoning.sources) && reasoning.sources.length === 0) {
-            reasoning.sources = ['agent'];
-        }
-        // V3 content 直透
-        const contentObj = params.content && typeof params.content === 'object'
-            ? params.content
-            : { markdown: '', pattern: '' };
-        const data = {
-            ...systemFields,
-            title: params.title || '',
-            description: params.description || '',
-            tags: params.tags || [],
-            trigger: params.trigger || '',
-            kind: params.kind || 'pattern',
-            topicHint: params.topicHint || '',
-            whenClause: params.whenClause || '',
-            doClause: params.doClause || '',
-            dontClause: params.dontClause || '',
-            coreCode: contentObj.pattern || '',
-            content: contentObj,
-            reasoning,
-            // V3 扩展字段直透
-            scope: params.scope || '',
-            complexity: params.complexity || '',
-            headers: params.headers || [],
-            // 注意: sourceFile 由 KnowledgeFileWriter.persist() 自动设置，
-            // 不应从 AI params/reasoning.sources 取值（那是项目源文件路径，不是知识文件路径）
-            sourceFile: '',
-            // 7.3.9 agentNotes/aiInsight 注入
             agentNotes: dimMeta
                 ? { dimensionId: dimMeta.id, outputType: dimMeta.outputType || 'candidate' }
                 : null,
-            aiInsight: reasoning.whyStandard || params.description || null,
         };
         if (dimMeta && ctx.source === 'system') {
             const displayGroup = DIMENSION_DISPLAY_GROUP[dimMeta.id] || dimMeta.id;
-            data.tags = [...new Set([...(data.tags || []), displayGroup])];
+            item.tags = [...new Set([...(item.tags || []), displayGroup])];
         }
-        const saved = await knowledgeService.create(data, { userId: 'agent' });
-        // ── QualityScorer 自动评分 ──
-        try {
-            await knowledgeService.updateQuality(saved.id, { userId: 'agent' });
+        // ── 委托 RecipeProductionGateway 统一管道 ──
+        const { RecipeProductionGateway } = await import('#service/knowledge/RecipeProductionGateway.js');
+        const gateway = new RecipeProductionGateway({
+            knowledgeService: ctx.container.get('knowledgeService'),
+            projectRoot: ctx.projectRoot,
+            logger: ctx.logger,
+            proposalRepository: ctx.container.get('proposalRepository') ?? null,
+        });
+        const gatewayResult = await gateway.create({
+            source: 'agent-tool',
+            items: [item],
+            options: {
+                skipSimilarityCheck: true,
+                skipConsolidation: true,
+                supersedes: params.supersedes,
+                existingTitles: ctx._submittedTitles,
+                existingFingerprints: ctx._submittedPatterns,
+                systemInjectedFields: dimMeta && ctx.source === 'system' ? getSystemInjectedFields() : undefined,
+                userId: 'agent',
+            },
+        });
+        // ── 映射 Gateway 结果 → 原有返回格式 ──
+        if (gatewayResult.rejected.length > 0) {
+            const rej = gatewayResult.rejected[0];
+            ctx.logger?.info(`[submit_knowledge] ✗ validator rejected: ${rej.errors.join('; ')}`);
+            return {
+                status: 'rejected',
+                error: rej.errors.join('\n'),
+                warnings: rej.warnings,
+                hint: '请根据错误信息调整内容后重新提交。',
+            };
         }
-        catch {
-            /* best effort — 不阻塞创建流程 */
+        if (gatewayResult.created.length > 0) {
+            const created = gatewayResult.created[0];
+            if (gatewayResult.supersedeProposal) {
+                return { ...created.raw, _supersedeProposal: gatewayResult.supersedeProposal };
+            }
+            return created.raw;
         }
-        return saved;
+        return { status: 'error', error: 'No items created' };
     },
 };
 // ────────────────────────────────────────────────────────────

package/dist/lib/cli/AiScanService.js

@@ -38,10 +38,10 @@ export class AiScanService {
         // 1. 初始化 AgentFactory (内置 AI Provider + ToolExecutionPipeline + 中间件)
         try {
             this.agentFactory = this.container.get('agentFactory');
-            // 验证 AI Provider 可用性
-            const aiProvider = this.container.singletons?.aiProvider;
-            if (!aiProvider || aiProvider.name === 'mock') {
-                throw new Error('AI Provider 未配置或为 mock');
+            // 通过 AiProviderManager 统一检查 AI 可用性
+            const manager = this.container.singletons?._aiProviderManager;
+            if (manager.isMock) {
+                throw new Error('AI Provider 为 mock 模式');
             }
         }
         catch (err) {
@@ -97,7 +97,7 @@ export class AiScanService {
                         recipe.source = 'ai-scan';
                         recipe.tags = [...new Set([...(recipe.tags || []), 'ai-scan', file.targetName])];
                         recipe.moduleName = file.targetName;
-                        recipe.sourceFile = file.relativePath || file.name;
+                        // 注意：不设置 sourceFile，由 KnowledgeFileWriter 持久化时自动设置为 md 文件路径
                         if (!recipe.aiInsight && recipe.description) {
                             recipe.aiInsight = recipe.description;
                         }

package/dist/lib/cli/KnowledgeSyncService.js

@@ -348,7 +348,7 @@ export class KnowledgeSyncService {
                SET lifecycle = 'deprecated', 
                    rejectionReason = ?, 
                    updatedAt = ?
-               WHERE id = ?`).run('source file deleted (orphan)', now, row.id);
+               WHERE id = ?`).run('源文件已删除（孤儿条目）', now, row.id);
                     }
                 }
             }

package/dist/lib/core/AstAnalyzer.d.ts

@@ -262,3 +262,4 @@ declare function checkProtocolConformance(source: string, lang: string, classNam
     classDeclLine: number | undefined;
 };
 export { analyzeFile, analyzeProject, generateContextForAgent, isAvailable, supportedLanguages, findCallExpressions, findPatternInContext, checkProtocolConformance, parseToTree, };
+export type { ProjectAnalysisResult };

package/dist/lib/core/discovery/ConfigWatcher.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ConfigWatcher — 构建配置文件热更新监听器
+ *
+ * 监听自研构建系统的配置文件变更，执行增量重解析并通知下游服务。
+ *
+ * 核心策略：
+ *   - debounce 3s（配置文件常有连续保存）
+ *   - MD5 hash 差量检测避免无效重解析
+ *   - 60s 最大频率保护（防 git checkout 等批量变更风暴）
+ *   - 增量解析：单文件变更只影响对应模块
+ *   - 通过 SignalBus 触发 PanoramaService 缓存失效
+ *   - 通过 RealtimeService 推送 Dashboard WebSocket 事件
+ *
+ * @module ConfigWatcher
+ */
+import type { SignalBus } from '#infra/signal/SignalBus.js';
+/** 变更类型：仅影响范围不同 */
+type ChangeScope = 'full' | 'module' | 'overlay';
+interface ConfigChangeEvent {
+    /** 变更的文件列表 */
+    changedFiles: Array<{
+        path: string;
+        scope: ChangeScope;
+        moduleName?: string;
+    }>;
+    /** 配置系统 ID */
+    systemId: string;
+    /** 事件触发时间 */
+    timestamp: number;
+}
+export interface ConfigWatcherOptions {
+    /** 项目根目录 */
+    projectRoot: string;
+    /** 配置系统 ID（easybox / tuist / xcodegen）或自定义 */
+    systemId: string;
+    /** 自定义 watch patterns（当 systemId 不在内置表中时） */
+    watchPatterns?: string[];
+    /** 信号总线（触发缓存失效） */
+    signalBus?: SignalBus | null;
+    /** 变更回调（用于外部通知，如 RealtimeService） */
+    onChange?: (event: ConfigChangeEvent) => void;
+    /** debounce 毫秒数（默认 3000） */
+    debounceMs?: number;
+    /** 全量重建最小间隔毫秒（默认 60000） */
+    fullRebuildIntervalMs?: number;
+}
+export declare class ConfigWatcher {
+    #private;
+    constructor(options: ConfigWatcherOptions);
+    /**
+     * 启动文件监听。异步解析初始文件 hash 并注册 fs.watch。
+     * 自动注册 shutdown hook 以清理资源。
+     */
+    start(): Promise<void>;
+    /**
+     * 停止监听，释放所有 fs.watch 资源
+     */
+    dispose(): void;
+    /** 是否正在监听 */
+    get active(): boolean;
+    /** 监听的文件数 */
+    get watchedFileCount(): number;
+}
+export {};