autosnippet 3.3.5 → 3.3.7

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;
@@ -61,6 +61,7 @@ export declare class KnowledgeEntry {
         from: string;
         to: string;
         at: number;
+        by?: string;
     }>;
     autoApprovable: boolean;
     stagingDeadline: number | null;
@@ -104,29 +105,59 @@ 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;
         error?: string;
     };
+    /**
+     * 将最后一条 lifecycleHistory 条目标记操作人。
+     * 由 KnowledgeService._lifecycleTransition() 在 entity method 执行后调用。
+     */
+    stampLastTransition(by: string): void;
     /** 是否处于候选阶段 */
     isCandidate(): boolean;
     /** 是否可被 Guard/Search/Export 消费 */
@@ -165,114 +196,11 @@ 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 } */
-    _transition(to: string): {
+    _transition(to: string, by?: string): {
         success: boolean;
         error?: string;
     };

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);
@@ -152,6 +173,16 @@ export class KnowledgeEntry {
         }
         return result;
     }
+    /**
+     * 将最后一条 lifecycleHistory 条目标记操作人。
+     * 由 KnowledgeService._lifecycleTransition() 在 entity method 执行后调用。
+     */
+    stampLastTransition(by) {
+        const last = this.lifecycleHistory[this.lifecycleHistory.length - 1];
+        if (last) {
+            last.by = by;
+        }
+    }
     /* ═══ 谓词 ═══════════════════════════════════════════ */
     /** 是否处于候选阶段 */
     isCandidate() {
@@ -268,18 +299,22 @@ export class KnowledgeEntry {
     }
     /* ═══ 私有 ═══════════════════════════════════════════ */
     /** @returns } */
-    _transition(to) {
+    _transition(to, by) {
         if (!isValidTransition(this.lifecycle, to)) {
             return {
                 success: false,
                 error: `Invalid lifecycle transition: ${this.lifecycle} → ${to}`,
             };
         }
-        this.lifecycleHistory.push({
+        const entry = {
             from: this.lifecycle,
             to,
             at: this._now(),
-        });
+        };
+        if (by) {
+            entry.by = by;
+        }
+        this.lifecycleHistory.push(entry);
         this.lifecycle = to;
         this.updatedAt = this._now();
         return { success: true };

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/external/ai/AiProvider.d.ts

@@ -148,6 +148,13 @@ export declare class AiProvider {
     name: string;
     timeout: number;
     _fallbackFrom?: string;
+    /**
+     * Token 用量回调 — 每次 API 调用后触发（包括 chat / chatWithStructuredOutput / chatWithTools）
+     * 由外部（如 DI 容器）注入以实现全局 token 计量。
+     */
+    _onTokenUsage: ((usage: TokenUsage & {
+        source?: string;
+    }) => void) | null;
     constructor(config?: AiProviderConfig);
     _acquireRequestSlot(): Promise<void>;
     _releaseRequestSlot(): void;
@@ -158,6 +165,11 @@ export declare class AiProvider {
      * @param context {history: [], temperature, maxTokens}
      */
     chat(prompt: string, context?: ChatContext): Promise<string>;
+    /**
+     * 从 API 原始响应中提取 token 用量并触发回调。
+     * 子类在 chat() / chatWithStructuredOutput() 中调用。
+     */
+    _emitTokenUsage(usage: TokenUsage | null | undefined, source?: string): void;
     /** 摘要 - 对代码/文档生成结构化摘要 */
     summarize(code: string): Promise<unknown>;
     /** 向量嵌入 - 返回浮点数组 */

package/dist/lib/external/ai/AiProvider.js

@@ -21,6 +21,11 @@ export class AiProvider {
     name;
     timeout;
     _fallbackFrom;
+    /**
+     * Token 用量回调 — 每次 API 调用后触发（包括 chat / chatWithStructuredOutput / chatWithTools）
+     * 由外部（如 DI 容器）注入以实现全局 token 计量。
+     */
+    _onTokenUsage = null;
     constructor(config = {}) {
         this.model = config.model || '';
         this.apiKey = config.apiKey || '';
@@ -79,6 +84,25 @@ export class AiProvider {
     async chat(prompt, context = {}) {
         throw new Error(`${this.name}.chat() not implemented`);
     }
+    /**
+     * 从 API 原始响应中提取 token 用量并触发回调。
+     * 子类在 chat() / chatWithStructuredOutput() 中调用。
+     */
+    _emitTokenUsage(usage, source) {
+        if (!usage || !this._onTokenUsage) {
+            return;
+        }
+        const total = (usage.inputTokens || 0) + (usage.outputTokens || 0);
+        if (total === 0) {
+            return;
+        }
+        try {
+            this._onTokenUsage({ ...usage, source });
+        }
+        catch {
+            /* token tracking should never break execution */
+        }
+    }
     /** 摘要 - 对代码/文档生成结构化摘要 */
     async summarize(code) {
         throw new Error(`${this.name}.summarize() not implemented`);