autosnippet 3.3.4 → 3.3.6

package/dist/lib/domain/dimension/UnifiedDimension.d.ts

@@ -0,0 +1,61 @@
+/**
+ * UnifiedDimension — 统一维度类型定义
+ *
+ * Bootstrap / Panorama / Rescan 共用的维度接口，
+ * 消除三套维度体系之间的 ID 不一致和字段缺失问题。
+ *
+ * 设计文档: docs/copilot/unified-dimension-design.md §4
+ *
+ * @module domain/dimension/UnifiedDimension
+ */
+/** 统一维度定义 — Bootstrap/Panorama/Rescan 共用 */
+export interface UnifiedDimension {
+    /** 维度唯一 ID，kebab-case */
+    readonly id: string;
+    /** 维度中文标签（Dashboard 分组标签） */
+    readonly label: string;
+    /** 层级: universal | language | framework */
+    readonly layer: 'universal' | 'language' | 'framework';
+    /** Lucide 图标名 */
+    readonly icon: string;
+    /** Tailwind 颜色族（如 'violet', 'fuchsia', 'sky'） */
+    readonly colorFamily: string;
+    /** 提取指南 — 告诉 Agent 从项目中挖掘什么 */
+    readonly extractionGuide: string;
+    /** 允许的 knowledgeType */
+    readonly allowedKnowledgeTypes: readonly string[];
+    /** 输出模式（当前阶段仅 candidate-only，Skill 后续规划） */
+    readonly outputMode: 'candidate-only';
+    /** 健康评估描述 */
+    readonly qualityDescription: string;
+    /** 主匹配字段: topicHint */
+    readonly matchTopics: readonly string[];
+    /** 次匹配字段: category */
+    readonly matchCategories: readonly string[];
+    /** 维度权重 (0-1, Panorama 加权平均) */
+    readonly weight: number;
+    /** gap 时的建议主题 */
+    readonly suggestedTopics: readonly string[];
+    /** 关联模块角色 (gap 优先级推断) */
+    readonly relatedRoles: readonly string[];
+    readonly conditions?: {
+        readonly languages?: readonly string[];
+        readonly frameworks?: readonly string[];
+    };
+    /** 1=最先 (Tier 1), 2=中间, 3=最后 */
+    readonly tierHint?: number;
+    /** Dashboard 展示分组 */
+    readonly displayGroup: 'architecture' | 'best-practice' | 'data-event-flow' | 'deep-scan';
+}
+/** Layer 1: 通用维度 ID */
+export declare const UNIVERSAL_DIM_IDS: readonly ["architecture", "coding-standards", "design-patterns", "error-resilience", "concurrency-async", "data-event-flow", "networking-api", "ui-interaction", "testing-quality", "security-auth", "performance-optimization", "observability-logging", "agent-guidelines"];
+/** Layer 2: 语言维度 ID */
+export declare const LANGUAGE_DIM_IDS: readonly ["swift-objc-idiom", "ts-js-module", "python-structure", "jvm-annotation", "go-module", "rust-ownership", "csharp-dotnet"];
+/** Layer 3: 框架维度 ID */
+export declare const FRAMEWORK_DIM_IDS: readonly ["react-patterns", "vue-patterns", "spring-patterns", "swiftui-patterns", "django-fastapi"];
+export type UniversalDimId = (typeof UNIVERSAL_DIM_IDS)[number];
+export type LanguageDimId = (typeof LANGUAGE_DIM_IDS)[number];
+export type FrameworkDimId = (typeof FRAMEWORK_DIM_IDS)[number];
+export type DimensionId = UniversalDimId | LanguageDimId | FrameworkDimId;
+/** 所有维度 ID 数组 */
+export declare const ALL_DIMENSION_IDS: readonly ["architecture", "coding-standards", "design-patterns", "error-resilience", "concurrency-async", "data-event-flow", "networking-api", "ui-interaction", "testing-quality", "security-auth", "performance-optimization", "observability-logging", "agent-guidelines", "swift-objc-idiom", "ts-js-module", "python-structure", "jvm-annotation", "go-module", "rust-ownership", "csharp-dotnet", "react-patterns", "vue-patterns", "spring-patterns", "swiftui-patterns", "django-fastapi"];

package/dist/lib/domain/dimension/UnifiedDimension.js

@@ -0,0 +1,53 @@
+/**
+ * UnifiedDimension — 统一维度类型定义
+ *
+ * Bootstrap / Panorama / Rescan 共用的维度接口，
+ * 消除三套维度体系之间的 ID 不一致和字段缺失问题。
+ *
+ * 设计文档: docs/copilot/unified-dimension-design.md §4
+ *
+ * @module domain/dimension/UnifiedDimension
+ */
+// ═══════════════════════════════════════════════════════════
+// 维度 ID 常量
+// ═══════════════════════════════════════════════════════════
+/** Layer 1: 通用维度 ID */
+export const UNIVERSAL_DIM_IDS = [
+    'architecture',
+    'coding-standards',
+    'design-patterns',
+    'error-resilience',
+    'concurrency-async',
+    'data-event-flow',
+    'networking-api',
+    'ui-interaction',
+    'testing-quality',
+    'security-auth',
+    'performance-optimization',
+    'observability-logging',
+    'agent-guidelines',
+];
+/** Layer 2: 语言维度 ID */
+export const LANGUAGE_DIM_IDS = [
+    'swift-objc-idiom',
+    'ts-js-module',
+    'python-structure',
+    'jvm-annotation',
+    'go-module',
+    'rust-ownership',
+    'csharp-dotnet',
+];
+/** Layer 3: 框架维度 ID */
+export const FRAMEWORK_DIM_IDS = [
+    'react-patterns',
+    'vue-patterns',
+    'spring-patterns',
+    'swiftui-patterns',
+    'django-fastapi',
+];
+/** 所有维度 ID 数组 */
+export const ALL_DIMENSION_IDS = [
+    ...UNIVERSAL_DIM_IDS,
+    ...LANGUAGE_DIM_IDS,
+    ...FRAMEWORK_DIM_IDS,
+];

package/dist/lib/domain/dimension/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * dimension domain — 统一维度体系
+ *
+ * @module domain/dimension
+ */
+export { DimensionCopy } from './DimensionCopy.js';
+export { buildTierPlan, classifyRecipeToDimension, DIMENSION_DISPLAY_GROUP, DIMENSION_REGISTRY, getDimension, getDimensionsByLayer, resolveActiveDimensions, } from './DimensionRegistry.js';
+export { getDimensionFocusKeywords, getDimensionSOP, PRE_SUBMIT_CHECKLIST, sopToCompactText, } from './DimensionSop.js';
+export type { DimensionId, FrameworkDimId, LanguageDimId, UnifiedDimension, UniversalDimId, } from './UnifiedDimension.js';
+export { ALL_DIMENSION_IDS, FRAMEWORK_DIM_IDS, LANGUAGE_DIM_IDS, UNIVERSAL_DIM_IDS, } from './UnifiedDimension.js';

package/dist/lib/domain/dimension/index.js

@@ -0,0 +1,9 @@
+/**
+ * dimension domain — 统一维度体系
+ *
+ * @module domain/dimension
+ */
+export { DimensionCopy } from './DimensionCopy.js';
+export { buildTierPlan, classifyRecipeToDimension, DIMENSION_DISPLAY_GROUP, DIMENSION_REGISTRY, getDimension, getDimensionsByLayer, resolveActiveDimensions, } from './DimensionRegistry.js';
+export { getDimensionFocusKeywords, getDimensionSOP, PRE_SUBMIT_CHECKLIST, sopToCompactText, } from './DimensionSop.js';
+export { ALL_DIMENSION_IDS, FRAMEWORK_DIM_IDS, LANGUAGE_DIM_IDS, UNIVERSAL_DIM_IDS, } from './UnifiedDimension.js';

package/dist/lib/domain/knowledge/FieldSpec.d.ts

@@ -54,7 +54,7 @@ export declare const V3_FIELD_SPEC: ({
     systemInjected?: undefined;
 })[];
 export declare const STANDARD_CATEGORIES: string[];
-/** category 白名单 — Bootstrap 维度展示分组 + 特殊流程中的合法 category */
+/** category 白名单 — 统一维度 ID + 特殊流程中的合法 category */
 export declare const WHITELISTED_CATEGORIES: string[];
 export declare const VALID_KINDS: string[];
 export declare const VALID_TOPIC_HINTS: string[];

package/dist/lib/domain/knowledge/FieldSpec.js

@@ -32,7 +32,7 @@ export const V3_FIELD_SPEC = [
         name: 'title',
         level: FieldLevel.REQUIRED,
         type: 'string',
-        rule: '中文 ≤20 字，引用项目真实类名',
+        rule: '中文 ≤20 字，引用项目真实类名（不以项目名开头）',
         pipeline: 'identity + dedup + search + QualityScorer(completeness 0.25)',
     },
     {
@@ -226,24 +226,37 @@ export const STANDARD_CATEGORIES = [
     'UI',
     'Utility',
 ];
-/** category 白名单 — Bootstrap 维度展示分组 + 特殊流程中的合法 category */
+/** category 白名单 — 统一维度 ID + 特殊流程中的合法 category */
 export const WHITELISTED_CATEGORIES = [
-    // Bootstrap 维度展示分组 (DIMENSION_DISPLAY_GROUP 输出值)
+    // ── Layer 1: 通用维度 ──
     'architecture',
-    'best-practice',
-    'event-and-data-flow',
-    'objc-deep-scan',
+    'coding-standards',
+    'design-patterns',
+    'error-resilience',
+    'concurrency-async',
+    'data-event-flow',
+    'networking-api',
+    'ui-interaction',
+    'testing-quality',
+    'security-auth',
+    'performance-optimization',
+    'observability-logging',
     'agent-guidelines',
-    // 维度原始 ID (当 DIMENSION_DISPLAY_GROUP 无映射时作为 fallback)
-    'code-pattern',
-    'code-standard',
-    'project-profile',
-    'category-scan',
-    'module-export-scan',
-    'framework-convention-scan',
-    'python-package-scan',
-    'jvm-annotation-scan',
-    // 特殊来源
+    // ── Layer 2: 语言维度 ──
+    'swift-objc-idiom',
+    'ts-js-module',
+    'python-structure',
+    'jvm-annotation',
+    'go-module',
+    'rust-ownership',
+    'csharp-dotnet',
+    // ── Layer 3: 框架维度 ──
+    'react-patterns',
+    'vue-patterns',
+    'spring-patterns',
+    'swiftui-patterns',
+    'django-fastapi',
+    // ── 特殊来源 ──
     'bootstrap',
     'knowledge',
     'general',

package/dist/lib/domain/knowledge/KnowledgeEntry.d.ts

@@ -1,4 +1,4 @@
-import type { Guard } from './values/Constraints.js';
+import type { KnowledgeEntryWire } from '#types/knowledge-wire.js';
 import { Constraints, Content, Quality, Reasoning, Relations, Stats } from './values/index.js';
 export interface KnowledgeEntryProps {
     id?: string;
@@ -104,24 +104,49 @@ export declare class KnowledgeEntry {
     publishedBy: string | null;
     constructor(props?: KnowledgeEntryProps);
     /**
-     * 发布 (pending → active)
-     * @returns }
+     * 发布 (pending|staging|evolving → active)
      */
     publish(publisher: string): {
         success: boolean;
         error?: string;
     };
     /**
-     * 弃用 (pending|active → deprecated)
-     * @returns }
+     * 进入暂存期 (pending → staging)
+     */
+    stage(): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * 进入进化态 (active → evolving)
+     */
+    evolve(): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * 进入衰退观察 (active|evolving → decaying)
+     */
+    decay(): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * 恢复为已发布 (decaying|evolving → active)，不更新 publishedAt
+     */
+    restore(): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * 弃用 (pending|active|decaying → deprecated)
      */
     deprecate(reason: string): {
         success: boolean;
         error?: string;
     };
     /**
-     * 重新激活 (deprecated → pending)
-     * @returns }
+     * 重新激活 (deprecated|staging → pending)
      */
     reactivate(): {
         success: boolean;
@@ -165,110 +190,7 @@ export declare class KnowledgeEntry {
      * Domain → JSON (camelCase 直出，全链路统一)
      * 注意: tags 保留原始值（含系统标签），对外 API 使用 sanitizeForAPI() 过滤
      */
-    toJSON(): {
-        id: string;
-        title: string;
-        description: string;
-        lifecycle: string;
-        lifecycleHistory: {
-            from: string;
-            to: string;
-            at: number;
-        }[];
-        autoApprovable: boolean;
-        language: string;
-        category: string;
-        kind: string;
-        knowledgeType: string;
-        complexity: string;
-        scope: string;
-        difficulty: string | null;
-        tags: string[];
-        trigger: string;
-        topicHint: string;
-        whenClause: string;
-        doClause: string;
-        dontClause: string;
-        coreCode: string;
-        usageGuide: string;
-        content: {
-            pattern: string;
-            markdown: string;
-            rationale: string;
-            steps: {
-                title?: string;
-                description?: string;
-                code?: string;
-            }[];
-            codeChanges: {
-                file: string;
-                before: string;
-                after: string;
-                explanation: string;
-            }[];
-            verification: {
-                method?: string;
-                expected_result?: string;
-                test_code?: string;
-            } | null;
-        };
-        relations: {
-            [x: string]: import("./values/Relations.js").RelationEntry[];
-        };
-        constraints: {
-            guards: Guard[];
-            boundaries: string[];
-            preconditions: string[];
-            sideEffects: string[];
-        };
-        reasoning: {
-            whyStandard: string;
-            sources: string[];
-            confidence: number;
-            qualitySignals: Record<string, number>;
-            alternatives: string[];
-        };
-        quality: {
-            completeness: number;
-            adaptation: number;
-            documentation: number;
-            overall: number;
-            grade: string;
-        };
-        stats: {
-            views: number;
-            adoptions: number;
-            applications: number;
-            guardHits: number;
-            searchHits: number;
-            authority: number;
-            lastHitAt: number | null;
-            lastSearchedAt: number | null;
-            lastGuardHitAt: number | null;
-            hitsLast30d: number;
-            hitsLast90d: number;
-            searchHitsLast30d: number;
-            version: number;
-            ruleFalsePositiveRate: number | null;
-        };
-        headers: string[];
-        headerPaths: string[];
-        moduleName: string;
-        includeHeaders: boolean;
-        agentNotes: string | null;
-        aiInsight: string | null;
-        reviewedBy: string | null;
-        reviewedAt: number | null;
-        rejectionReason: string | null;
-        source: string;
-        sourceFile: string | null;
-        sourceCandidateId: string | null;
-        createdBy: string;
-        createdAt: number;
-        updatedAt: number;
-        publishedAt: number | null;
-        publishedBy: string | null;
-    };
+    toJSON(): KnowledgeEntryWire;
     /** JSON → Domain (camelCase 直入) */
     static fromJSON(data: unknown): KnowledgeEntry;
     /** @returns } */

package/dist/lib/domain/knowledge/KnowledgeEntry.js

@@ -116,8 +116,7 @@ export class KnowledgeEntry {
     }
     /* ═══ 生命周期操作 ═══════════════════════════════════ */
     /**
-     * 发布 (pending → active)
-     * @returns }
+     * 发布 (pending|staging|evolving → active)
      */
     publish(publisher) {
         if (!this.isValid()) {
@@ -131,8 +130,31 @@ export class KnowledgeEntry {
         return result;
     }
     /**
-     * 弃用 (pending|active → deprecated)
-     * @returns }
+     * 进入暂存期 (pending → staging)
+     */
+    stage() {
+        return this._transition(Lifecycle.STAGING);
+    }
+    /**
+     * 进入进化态 (active → evolving)
+     */
+    evolve() {
+        return this._transition(Lifecycle.EVOLVING);
+    }
+    /**
+     * 进入衰退观察 (active|evolving → decaying)
+     */
+    decay() {
+        return this._transition(Lifecycle.DECAYING);
+    }
+    /**
+     * 恢复为已发布 (decaying|evolving → active)，不更新 publishedAt
+     */
+    restore() {
+        return this._transition(Lifecycle.ACTIVE);
+    }
+    /**
+     * 弃用 (pending|active|decaying → deprecated)
      */
     deprecate(reason) {
         const result = this._transition(Lifecycle.DEPRECATED);
@@ -142,8 +164,7 @@ export class KnowledgeEntry {
         return result;
     }
     /**
-     * 重新激活 (deprecated → pending)
-     * @returns }
+     * 重新激活 (deprecated|staging → pending)
      */
     reactivate() {
         const result = this._transition(Lifecycle.PENDING);

package/dist/lib/domain/knowledge/KnowledgeRepository.d.ts

@@ -16,6 +16,7 @@ export interface PaginatedResult {
 export declare class KnowledgeRepository {
     create(entry: KnowledgeEntry): Promise<KnowledgeEntry>;
     findById(id: string): Promise<KnowledgeEntry | null>;
+    findByTitle(title: string): Promise<KnowledgeEntry | null>;
     findWithPagination(filters?: Record<string, unknown>, options?: PaginationOptions & {
         orderBy?: string;
         order?: string;

package/dist/lib/domain/knowledge/KnowledgeRepository.js

@@ -11,6 +11,9 @@ export class KnowledgeRepository {
     async findById(id) {
         throw new Error('Not implemented');
     }
+    async findByTitle(title) {
+        throw new Error('Not implemented');
+    }
     async findWithPagination(filters, options) {
         throw new Error('Not implemented');
     }

package/dist/lib/domain/knowledge/Lifecycle.js

@@ -33,7 +33,7 @@ const VALID_TRANSITIONS = {
     [Lifecycle.PENDING]: [Lifecycle.STAGING, Lifecycle.ACTIVE, Lifecycle.DEPRECATED],
     [Lifecycle.STAGING]: [Lifecycle.ACTIVE, Lifecycle.PENDING],
     [Lifecycle.ACTIVE]: [Lifecycle.EVOLVING, Lifecycle.DECAYING, Lifecycle.DEPRECATED],
-    [Lifecycle.EVOLVING]: [Lifecycle.ACTIVE, Lifecycle.DECAYING],
+    [Lifecycle.EVOLVING]: [Lifecycle.STAGING, Lifecycle.ACTIVE, Lifecycle.DECAYING],
     [Lifecycle.DECAYING]: [Lifecycle.ACTIVE, Lifecycle.DEPRECATED],
     [Lifecycle.DEPRECATED]: [Lifecycle.PENDING],
 };

package/dist/lib/domain/knowledge/StyleGuide.d.ts

@@ -6,7 +6,7 @@
  *
  * @module shared/StyleGuide
  */
-export declare const PROJECT_SNAPSHOT_STYLE_GUIDE = "# \u300C\u9879\u76EE\u7279\u5199\u300D\u5199\u4F5C\u8981\u6C42\n\nsubmit_knowledge \u7684 content.markdown \u5B57\u6BB5\u5FC5\u987B\u662F\u300C\u9879\u76EE\u7279\u5199\u300D\u3002\n\n## \u4EC0\u4E48\u662F\u300C\u9879\u76EE\u7279\u5199\u300D\n\u5C06\u4E00\u79CD\u6280\u672F\u7684**\u57FA\u672C\u7528\u6CD5**\u4E0E**\u672C\u9879\u76EE\u7684\u5177\u4F53\u7279\u5F81**\u878D\u5408\u4E3A\u4E00\u4F53\u3002\n\n## \u56DB\u5927\u6838\u5FC3\u5185\u5BB9\n1. **\u9879\u76EE\u9009\u62E9\u4E86\u4EC0\u4E48** \u2014 \u91C7\u7528\u4E86\u54EA\u79CD\u5199\u6CD5/\u6A21\u5F0F/\u7EA6\u5B9A\n2. **\u4E3A\u4EC0\u4E48\u8FD9\u6837\u9009** \u2014 \u7EDF\u8BA1\u5206\u5E03\u3001\u5360\u6BD4\u3001\u5386\u53F2\u51B3\u7B56\n3. **\u9879\u76EE\u7981\u6B62\u4EC0\u4E48** \u2014 \u53CD\u6A21\u5F0F\u3001\u5DF2\u5E9F\u5F03\u5199\u6CD5\n4. **\u65B0\u4EE3\u7801\u600E\u4E48\u5199** \u2014 \u53EF\u76F4\u63A5\u590D\u5236\u4F7F\u7528\u7684\u4EE3\u7801\u6A21\u677F + \u6765\u6E90\u6807\u6CE8 (\u6765\u6E90: FileName.ext:\u884C\u53F7)\n\n## \u683C\u5F0F\u8981\u6C42\n- \u6807\u9898\u4F7F\u7528\u9879\u76EE\u771F\u5B9E\u7C7B\u540D/\u524D\u7F00\uFF0C\u4E0D\u7528\u5360\u4F4D\u540D\n- \u4EE3\u7801\u6765\u6E90\u6807\u6CE8: (\u6765\u6E90: FileName.ext:\u884C\u53F7)\n- \u4E0D\u8981\u7EAF\u4EE3\u7801\u7F57\u5217\uFF0C\u5FC5\u987B\u6709\u9879\u76EE\u4E0A\u4E0B\u6587\n- \u6807\u9898\u548C\u6B63\u6587\u4E2D\u4E0D\u5F97\u51FA\u73B0 \"Agent\" \u5B57\u6837";
+export declare const PROJECT_SNAPSHOT_STYLE_GUIDE = "# \u300C\u9879\u76EE\u7279\u5199\u300D\u5199\u4F5C\u8981\u6C42\n\nsubmit_knowledge \u7684 content.markdown \u5B57\u6BB5\u5FC5\u987B\u662F\u300C\u9879\u76EE\u7279\u5199\u300D\u3002\n\n## \u4EC0\u4E48\u662F\u300C\u9879\u76EE\u7279\u5199\u300D\n\u5C06\u4E00\u79CD\u6280\u672F\u7684**\u57FA\u672C\u7528\u6CD5**\u4E0E**\u672C\u9879\u76EE\u7684\u5177\u4F53\u7279\u5F81**\u878D\u5408\u4E3A\u4E00\u4F53\u3002\n\n## \u56DB\u5927\u6838\u5FC3\u5185\u5BB9\n1. **\u9879\u76EE\u9009\u62E9\u4E86\u4EC0\u4E48** \u2014 \u91C7\u7528\u4E86\u54EA\u79CD\u5199\u6CD5/\u6A21\u5F0F/\u7EA6\u5B9A\n2. **\u4E3A\u4EC0\u4E48\u8FD9\u6837\u9009** \u2014 \u7EDF\u8BA1\u5206\u5E03\u3001\u5360\u6BD4\u3001\u5386\u53F2\u51B3\u7B56\n3. **\u9879\u76EE\u7981\u6B62\u4EC0\u4E48** \u2014 \u53CD\u6A21\u5F0F\u3001\u5DF2\u5E9F\u5F03\u5199\u6CD5\n4. **\u65B0\u4EE3\u7801\u600E\u4E48\u5199** \u2014 \u53EF\u76F4\u63A5\u590D\u5236\u4F7F\u7528\u7684\u4EE3\u7801\u6A21\u677F + \u6765\u6E90\u6807\u6CE8 (\u6765\u6E90: FileName.ext:\u884C\u53F7)\n\n## \u683C\u5F0F\u8981\u6C42\n- \u6807\u9898\u4F7F\u7528\u9879\u76EE\u771F\u5B9E\u7C7B\u540D/\u524D\u7F00\uFF0C\u4E0D\u7528\u5360\u4F4D\u540D\uFF0C\u4E0D\u4EE5\u9879\u76EE\u540D\u5F00\u5934\n- \u4EE3\u7801\u6765\u6E90\u6807\u6CE8: (\u6765\u6E90: FileName.ext:\u884C\u53F7)\n- \u4E0D\u8981\u7EAF\u4EE3\u7801\u7F57\u5217\uFF0C\u5FC5\u987B\u6709\u9879\u76EE\u4E0A\u4E0B\u6587\n- \u6807\u9898\u548C\u6B63\u6587\u4E2D\u4E0D\u5F97\u51FA\u73B0 \"Agent\" \u5B57\u6837";
 /** 生成 Cursor 交付字段规范文本（供 Producer STYLE_GUIDE 和 MissionBriefing 使用） */
 export declare function getCursorDeliverySpec(): string;
 /** 构建完整的 Producer STYLE_GUIDE（合并项目特写要求 + Cursor 交付字段规范） */

package/dist/lib/domain/knowledge/StyleGuide.js

@@ -22,7 +22,7 @@ submit_knowledge 的 content.markdown 字段必须是「项目特写」。
 4. **新代码怎么写** — 可直接复制使用的代码模板 + 来源标注 (来源: FileName.ext:行号)
 
 ## 格式要求
-- 标题使用项目真实类名/前缀，不用占位名
+- 标题使用项目真实类名/前缀，不用占位名，不以项目名开头
 - 代码来源标注: (来源: FileName.ext:行号)
 - 不要纯代码罗列，必须有项目上下文
 - 标题和正文中不得出现 "Agent" 字样`;

package/dist/lib/domain/knowledge/UnifiedValidator.js

@@ -132,6 +132,12 @@ export class UnifiedValidator {
             if (!hasSourceRef) {
                 warnings.push('建议在内容中标注代码来源 (来源: FileName.ext:行号)');
             }
+            // 源码位置质量检查 — 优先使用完整相对路径
+            const hasFullPathRef = /来源[:：]\s*\S+\/\S+\.\w+:\d+/.test(markdown) || /\(\S+\/\S+\.\w+:\d+\)/.test(markdown);
+            const hasBareName = /来源[:：]\s*[A-Z]\w+\.\w+:\d+/.test(markdown) || /\([A-Z]\w+\.\w+:\d+\)/.test(markdown);
+            if (hasBareName && !hasFullPathRef) {
+                warnings.push('源码位置应使用完整相对路径+行号（如 Packages/ModuleName/Sources/.../FileName.swift:42），而非仅文件名');
+            }
         }
         // coreCode 语法完整性
         {
@@ -156,6 +162,15 @@ export class UnifiedValidator {
                 warnings.push(`内容仅 ${lines.length} 行 — 建议包含更多代码片段和设计意图描述`);
             }
         }
+        // reasoning.sources 路径质量检查 — 应包含路径分隔符，而非仅类名/文件名
+        const reasoning = candidate.reasoning;
+        const sources = reasoning?.sources;
+        if (Array.isArray(sources) && sources.length > 0) {
+            const bareSources = sources.filter((s) => typeof s === 'string' && !s.includes('/') && !s.includes('\\'));
+            if (bareSources.length > 0 && bareSources.length === sources.length) {
+                warnings.push(`reasoning.sources 中的路径缺少目录结构（如 "${bareSources[0]}"）— 应使用完整相对路径（如 Packages/ModuleName/Sources/.../FileName.swift）`);
+            }
+        }
     }
     // ── Layer 3: 去重 ────────────────────────────────────────
     #checkUniqueness(candidate, errors) {

package/dist/lib/domain/knowledge/values/Stats.d.ts

@@ -43,7 +43,7 @@ export declare class Stats {
     static from(input: unknown): Stats;
     /** 增加计数 */
     increment(counter: StatsCounter, delta?: number): Stats;
-    /** 记录一次命中，同时更新时间戳 */
+    /** 记录一次命中，同时更新时间戳（Unix 秒） */
     recordHit(counter: StatsCounter, timestamp?: number): Stats;
     /** 转换为 JSON */
     toJSON(): {

package/dist/lib/domain/knowledge/values/Stats.js

@@ -60,8 +60,8 @@ export class Stats {
         this[counter] += delta;
         return this;
     }
-    /** 记录一次命中，同时更新时间戳 */
-    recordHit(counter, timestamp = Date.now()) {
+    /** 记录一次命中，同时更新时间戳（Unix 秒） */
+    recordHit(counter, timestamp = Math.floor(Date.now() / 1000)) {
         this[counter] += 1;
         this.lastHitAt = timestamp;
         if (counter === 'searchHits') {

package/dist/lib/external/mcp/McpServer.js

@@ -36,7 +36,9 @@ import * as systemHandlers from './handlers/system.js';
 // ─── External Agent Bootstrap 新 handler ──────────────────────
 import { bootstrapExternal } from './handlers/bootstrap-external.js';
 import { dimensionComplete } from './handlers/dimension-complete-external.js';
+import { evolveExternal } from './handlers/evolve-external.js';
 import { panoramaHandler } from './handlers/panorama.js';
+import { rescanExternal } from './handlers/rescan-external.js';
 import { taskHandler } from './handlers/task.js';
 import { wikiRouter } from './handlers/wiki-external.js';
 // ─── McpServer 类 ─────────────────────────────────────────────
@@ -363,6 +365,8 @@ export class McpServer {
             autosnippet_panorama: (ctx, args) => panoramaHandler(ctx, args),
             // ── External Agent Bootstrap (v3.1) ──
             autosnippet_bootstrap: (ctx, _args) => bootstrapExternal(ctx),
+            autosnippet_rescan: (ctx, args) => rescanExternal(ctx, args),
+            autosnippet_evolve: (ctx, args) => evolveExternal(ctx, args),
             autosnippet_dimension_complete: (ctx, args) => dimensionComplete(ctx, args),
             autosnippet_wiki: (ctx, args) => wikiRouter(ctx, args),
             // ── Admin 层 (+4) ──

package/dist/lib/external/mcp/handlers/TargetClassifier.d.ts

@@ -6,6 +6,6 @@
  *   - 文件名 → 分析优先级推断
  */
 /** 根据 Target 名称推断模块职责 */
-export declare function inferTargetRole(targetName: string): "model" | "config" | "networking" | "ui" | "service" | "auth" | "core" | "storage" | "test" | "app" | "routing" | "utility" | "feature";
+export declare function inferTargetRole(targetName: string): "model" | "config" | "networking" | "ui" | "core" | "app" | "service" | "storage" | "feature" | "test" | "auth" | "routing" | "utility";
 /** 根据文件名推断分析优先级 */
 export declare function inferFilePriority(filename: string): "high" | "medium" | "low";

package/dist/lib/external/mcp/handlers/bootstrap/BootstrapSession.d.ts

@@ -15,18 +15,10 @@
  * @module bootstrap/BootstrapSession
  */
 import { SessionStore } from '#agent/memory/SessionStore.js';
+import type { DimensionDef } from '#types/project-snapshot.js';
+import type { SessionCacheShape } from '#types/snapshot-views.js';
 import type { DimensionQualityReport } from './ExternalSubmissionTracker.js';
 import { ExternalSubmissionTracker } from './ExternalSubmissionTracker.js';
-/** 维度定义 */
-export interface DimensionDef {
-    id: string;
-    label?: string;
-    skillWorthy?: boolean;
-    skillMeta?: {
-        name?: string;
-        description?: string;
-    };
-}
 /** Bootstrap 会话构造参数 */
 interface BootstrapSessionOpts {
     projectRoot: string;
@@ -61,7 +53,7 @@ export declare class BootstrapSession {
     completedDimensions: Map<string, DimensionCompletion>;
     crossDimensionHints: Record<string, CrossDimensionHint[]>;
     dimensions: DimensionDef[];
-    phaseCache: Record<string, unknown> | null;
+    snapshotCache: SessionCacheShape | null;
     sessionStore: SessionStore;
     submissionTracker: ExternalSubmissionTracker;
     /**
@@ -101,12 +93,12 @@ export declare class BootstrapSession {
      */
     getAccumulatedHints(): Record<string, CrossDimensionHint[]>;
     /**
-     * 缓存 Phase 1-4 分析结果
-     * @param cache { files, astData, entityGraph, depGraph, guardFindings, skills, ... }
+     * 缓存 Phase 1-4 分析结果（ProjectSnapshot 的 session cache 形式）
+     * @param cache toSessionCache(snapshot) 的返回值
      */
-    setPhaseCache(cache: Record<string, unknown> | null): void;
-    /** 获取 Phase 缓存（wiki_plan 复用） */
-    getPhaseCache(): Record<string, unknown> | null;
+    setSnapshotCache(cache: SessionCacheShape | null): void;
+    /** 获取 Snapshot 缓存（wiki_plan / dimension-complete 复用） */
+    getSnapshotCache(): SessionCacheShape | null;
     toJSON(): {
         id: string;
         projectRoot: string;