@gong-ym/ai-spec-auto 0.2.3

package/src/asset/asset-quality.js

@@ -0,0 +1,262 @@
+/**
+ * AssetQuality — 资产质量评分与排名
+ *
+ * 基于反馈和使用数据计算资产质量评分、使用指标、
+ * 反馈聚合、推荐依据和资产排名。
+ */
+
+const { createAssetFeedback, AssetFeedback } = require('./asset-feedback');
+const { createAssetInstall, AssetInstall } = require('./asset-install');
+
+// ============================================================
+// 评分权重
+// ============================================================
+
+const DEFAULT_WEIGHTS = {
+  averageRating: 0.4,
+  adoptionRate: 0.3,
+  failureRate: 0.2,
+  sampleSize: 0.1,
+};
+
+// ============================================================
+// AssetQuality 类
+// ============================================================
+
+class AssetQuality {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.storageDir] - NDJSON 持久化目录
+   */
+  constructor(options = {}) {
+    const storageDir = options.storageDir || null;
+    const path = require('path');
+
+    /** @type {AssetFeedback} */
+    this.feedback = createAssetFeedback({
+      storagePath: storageDir ? path.join(storageDir, 'quality-feedback.ndjson') : undefined,
+    });
+
+    /** @type {AssetInstall} */
+    this.installTracker = createAssetInstall({
+      storagePath: storageDir ? path.join(storageDir, 'quality-installs.ndjson') : undefined,
+    });
+  }
+
+  // ============================================================
+  // computeScore — 计算质量评分
+  // ============================================================
+
+  /**
+   * 计算资产质量评分
+   * @param {string} assetId
+   * @returns {object} QualityScore
+   */
+  computeScore(assetId) {
+    const feedbackSummary = this.feedback.getAssetSummary(assetId);
+    const usageMetrics = this.getUsageMetrics(assetId);
+    const avgRating = this.feedback.getAverageRating(assetId);
+
+    const dimensions = {
+      hitRate: this._computeHitRate(assetId),
+      failureRate: this._computeFailureRate(assetId),
+      repairRate: this._computeRepairRate(assetId),
+      adoptionRate: this._computeAdoptionRate(usageMetrics),
+      averageRating: avgRating,
+    };
+
+    const sampleSize = feedbackSummary.totalFeedbacks + usageMetrics.totalInstalls;
+    const overallScore = this._computeOverallScore(dimensions, sampleSize);
+
+    return {
+      assetId,
+      overallScore,
+      dimensions,
+      sampleSize,
+      computedAt: new Date().toISOString(),
+    };
+  }
+
+  // ============================================================
+  // getUsageMetrics — 使用指标
+  // ============================================================
+
+  /**
+   * 获取资产使用指标
+   * @param {string} assetId
+   * @returns {object}
+   */
+  getUsageMetrics(assetId) {
+    const installs = this.installTracker.list({ assetId });
+
+    const projects = new Set();
+    let upgradeCount = 0;
+    let failCount = 0;
+
+    for (const inst of installs) {
+      projects.add(inst.projectId);
+      if (inst.status === 'upgraded') upgradeCount++;
+      if (inst.status === 'failed') failCount++;
+    }
+
+    return {
+      totalInstalls: installs.length,
+      projectCount: projects.size,
+      upgradeCount,
+      failCount,
+    };
+  }
+
+  // ============================================================
+  // getFeedbackAggregation — 反馈聚合
+  // ============================================================
+
+  /**
+   * 获取反馈聚合
+   * @param {string} assetId
+   * @returns {object}
+   */
+  getFeedbackAggregation(assetId) {
+    return this.feedback.getAssetSummary(assetId);
+  }
+
+  // ============================================================
+  // getRecommendationBasis — 推荐依据
+  // ============================================================
+
+  /**
+   * 获取推荐依据
+   * @param {string} assetId
+   * @returns {object}
+   */
+  getRecommendationBasis(assetId) {
+    const score = this.computeScore(assetId);
+    const usage = this.getUsageMetrics(assetId);
+
+    let recommendationStrength = 'weak';
+    if (score.overallScore >= 80) {
+      recommendationStrength = 'strong';
+    } else if (score.overallScore >= 50) {
+      recommendationStrength = 'moderate';
+    }
+
+    return {
+      qualityScore: score.overallScore,
+      usageCount: usage.totalInstalls,
+      averageRating: score.dimensions.averageRating,
+      recommendationStrength,
+    };
+  }
+
+  // ============================================================
+  // rankAssets — 资产排名
+  // ============================================================
+
+  /**
+   * 资产排名
+   * @param {object} [filters]
+   * @param {number} [filters.limit] - 返回数量限制
+   * @returns {object[]}
+   */
+  rankAssets(filters = {}) {
+    // 收集所有有数据的资产 ID
+    const assetIds = new Set();
+    for (const record of this.feedback.list()) {
+      assetIds.add(record.assetId);
+    }
+    for (const record of this.installTracker.list()) {
+      assetIds.add(record.assetId);
+    }
+
+    // 计算每个资产的评分
+    const scored = [];
+    for (const assetId of assetIds) {
+      const score = this.computeScore(assetId);
+      scored.push(score);
+    }
+
+    // 按综合评分降序排列
+    scored.sort((a, b) => b.overallScore - a.overallScore);
+
+    if (filters.limit && filters.limit > 0) {
+      return scored.slice(0, filters.limit);
+    }
+
+    return scored;
+  }
+
+  // ============================================================
+  // 内部评分计算
+  // ============================================================
+
+  _computeOverallScore(dimensions, sampleSize) {
+    if (sampleSize === 0) return 0;
+
+    // 评分维度归一化到 0-100
+    const ratingScore = (dimensions.averageRating / 5) * 100;
+    const adoptionScore = Math.min(dimensions.adoptionRate * 100, 100);
+    const failureScore = Math.max(100 - dimensions.failureRate * 100, 0);
+    const sampleScore = Math.min(sampleSize * 2, 100); // 每个样本 2 分，上限 100
+
+    const weighted =
+      ratingScore * DEFAULT_WEIGHTS.averageRating +
+      adoptionScore * DEFAULT_WEIGHTS.adoptionRate +
+      failureScore * DEFAULT_WEIGHTS.failureRate +
+      sampleScore * DEFAULT_WEIGHTS.sampleSize;
+
+    return Math.round(weighted);
+  }
+
+  _computeHitRate(assetId) {
+    // 命中率 = 有反馈的安装数 / 总安装数
+    const installs = this.installTracker.list({ assetId });
+    if (installs.length === 0) return 0;
+    const feedbacks = this.feedback.list({ assetId });
+    const feedbackProjects = new Set(feedbacks.map(f => f.projectId));
+    const installProjects = new Set(installs.map(i => i.projectId));
+    let hits = 0;
+    for (const pid of installProjects) {
+      if (feedbackProjects.has(pid)) hits++;
+    }
+    return hits / installProjects.size;
+  }
+
+  _computeFailureRate(assetId) {
+    const installs = this.installTracker.list({ assetId });
+    if (installs.length === 0) return 0;
+    const failures = installs.filter(i => i.status === 'failed').length;
+    return failures / installs.length;
+  }
+
+  _computeRepairRate(assetId) {
+    // 修复率 = 已解决反馈 / 总反馈
+    const feedbacks = this.feedback.list({ assetId });
+    if (feedbacks.length === 0) return 0;
+    const resolved = feedbacks.filter(f => f.status === 'resolved').length;
+    return resolved / feedbacks.length;
+  }
+
+  _computeAdoptionRate(usageMetrics) {
+    // 采纳率 = 升级数 / 总安装数
+    if (usageMetrics.totalInstalls === 0) return 0;
+    return usageMetrics.upgradeCount / usageMetrics.totalInstalls;
+  }
+}
+
+// ============================================================
+// 工厂函数
+// ============================================================
+
+/**
+ * 创建资产质量评分器
+ * @param {object} [options]
+ * @returns {AssetQuality}
+ */
+function createAssetQuality(options) {
+  return new AssetQuality(options);
+}
+
+module.exports = {
+  createAssetQuality,
+  AssetQuality,
+};

package/src/asset/asset-registry.js

@@ -0,0 +1,387 @@
+/**
+ * AssetRegistry — 资产注册表
+ *
+ * 管理资产元数据的注册、查询、更新和注销，
+ * 支持 NDJSON 文件持久化与坏行容错。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { VALID_ASSET_TYPES } = require('./asset-package');
+const { redactObject } = require('../governance/audit-log');
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** 资产注册状态枚举 */
+const ASSET_REGISTRY_STATUSES = Object.freeze({
+  ACTIVE: 'active',
+  DEPRECATED: 'deprecated',
+  ARCHIVED: 'archived',
+});
+
+/** 合法状态值 */
+const VALID_REGISTRY_STATUSES = new Set(Object.values(ASSET_REGISTRY_STATUSES));
+
+// ============================================================
+// 必填字段与校验
+// ============================================================
+
+const REQUIRED_FIELDS = ['assetId', 'assetType', 'name', 'currentVersion'];
+
+function validateRegistration(meta) {
+  const errors = [];
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!meta[field] || typeof meta[field] !== 'string') {
+      errors.push(`${field} 必须为非空字符串`);
+    }
+  }
+
+  if (meta.assetType && !VALID_ASSET_TYPES.has(meta.assetType)) {
+    errors.push(`assetType 必须为 ${[...VALID_ASSET_TYPES].join('/')} 之一，当前值: ${meta.assetType}`);
+  }
+
+  if (meta.status && !VALID_REGISTRY_STATUSES.has(meta.status)) {
+    errors.push(`status 必须为 ${[...VALID_REGISTRY_STATUSES].join('/')} 之一，当前值: ${meta.status}`);
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+// ============================================================
+// AssetRegistry 类
+// ============================================================
+
+class AssetRegistry {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.storagePath] - NDJSON 持久化路径
+   * @param {number} [options.maxAssets] - 最大资产数
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, object>} */
+    this._assets = new Map();
+    /** @type {number} */
+    this._nextId = 1;
+    /** @type {string|null} */
+    this.storagePath = options.storagePath || null;
+    /** @type {number} */
+    this._maxAssets = options.maxAssets || 10000;
+    /** @type {object[]} */
+    this.loadErrors = [];
+
+    if (this.storagePath) {
+      this._loadFromFile();
+    }
+  }
+
+  // ============================================================
+  // NDJSON 持久化
+  // ============================================================
+
+  /** 从 NDJSON 文件加载 */
+  _loadFromFile() {
+    if (!this.storagePath) return;
+
+    try {
+      if (!fs.existsSync(this.storagePath)) return;
+    } catch {
+      return;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(this.storagePath, 'utf-8');
+    } catch {
+      return;
+    }
+
+    if (!content || !content.trim()) return;
+
+    const lines = content.split('\n');
+    this._assets.clear();
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      try {
+        const entry = JSON.parse(line);
+
+        // tombstone 记录（注销标记）
+        if (entry._action === 'unregister' && entry.assetId) {
+          this._assets.delete(entry.assetId);
+          continue;
+        }
+
+        // 正常记录
+        if (entry.assetId) {
+          this._assets.set(entry.assetId, entry);
+        }
+      } catch (err) {
+        this.loadErrors.push({
+          lineNumber: i + 1,
+          line: line.substring(0, 200),
+          message: err.message || 'JSON 解析失败',
+        });
+      }
+    }
+  }
+
+  /** 追加记录到 NDJSON 文件 */
+  _appendToFile(entry) {
+    if (!this.storagePath) return;
+
+    const dir = path.dirname(this.storagePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const line = JSON.stringify(entry) + '\n';
+    fs.appendFileSync(this.storagePath, line, 'utf-8');
+  }
+
+  // ============================================================
+  // register — 注册资产
+  // ============================================================
+
+  /**
+   * 注册资产元数据
+   * @param {object} meta - 资产元数据
+   * @returns {object} 标准化记录
+   */
+  register(meta) {
+    const validation = validateRegistration(meta);
+    if (!validation.ok) {
+      throw new Error(`注册校验失败: ${validation.errors.join('; ')}`);
+    }
+
+    if (this._assets.has(meta.assetId)) {
+      throw new Error(`资产已存在: ${meta.assetId}`);
+    }
+
+    if (this._assets.size >= this._maxAssets) {
+      throw new Error(`注册表已满，最大资产数: ${this._maxAssets}`);
+    }
+
+    const now = new Date().toISOString();
+    const record = {
+      assetId: meta.assetId,
+      assetType: meta.assetType,
+      name: meta.name,
+      description: meta.description || '',
+      source: meta.source || 'local',
+      currentVersion: meta.currentVersion,
+      status: meta.status || 'active',
+      tags: Array.isArray(meta.tags) ? [...meta.tags] : [],
+      owner: meta.owner || '',
+      createdAt: now,
+      updatedAt: now,
+      metadata: redactObject(meta.metadata || {}),
+    };
+
+    this._assets.set(record.assetId, record);
+    this._appendToFile(record);
+
+    return { ...record, metadata: { ...record.metadata } };
+  }
+
+  // ============================================================
+  // unregister — 注销资产
+  // ============================================================
+
+  /**
+   * 注销资产
+   * @param {string} assetId
+   * @returns {boolean}
+   */
+  unregister(assetId) {
+    if (!this._assets.has(assetId)) {
+      throw new Error(`资产不存在: ${assetId}`);
+    }
+
+    this._assets.delete(assetId);
+
+    // 写入 tombstone 记录
+    this._appendToFile({ _action: 'unregister', assetId, timestamp: new Date().toISOString() });
+
+    return true;
+  }
+
+  // ============================================================
+  // get — 获取单个资产
+  // ============================================================
+
+  /**
+   * 获取资产记录
+   * @param {string} assetId
+   * @returns {object|null}
+   */
+  get(assetId) {
+    const record = this._assets.get(assetId);
+    if (!record) return null;
+    return { ...record, metadata: { ...record.metadata } };
+  }
+
+  // ============================================================
+  // list — 多维查询
+  // ============================================================
+
+  /**
+   * 查询资产列表
+   * @param {object} [filters]
+   * @param {string} [filters.assetType]
+   * @param {string} [filters.source]
+   * @param {string} [filters.status]
+   * @param {string} [filters.keyword] - 匹配 name 和 description
+   * @param {number} [filters.limit]
+   * @returns {object[]}
+   */
+  list(filters = {}) {
+    let results = [...this._assets.values()];
+
+    if (filters.assetType) {
+      results = results.filter(r => r.assetType === filters.assetType);
+    }
+    if (filters.source) {
+      results = results.filter(r => r.source === filters.source);
+    }
+    if (filters.status) {
+      results = results.filter(r => r.status === filters.status);
+    }
+    if (filters.keyword) {
+      const kw = filters.keyword.toLowerCase();
+      results = results.filter(r =>
+        r.name.toLowerCase().includes(kw) ||
+        (r.description && r.description.toLowerCase().includes(kw))
+      );
+    }
+
+    if (filters.limit && filters.limit > 0) {
+      results = results.slice(0, filters.limit);
+    }
+
+    return results.map(r => ({ ...r, metadata: { ...r.metadata } }));
+  }
+
+  // ============================================================
+  // update — 更新资产元数据
+  // ============================================================
+
+  /**
+   * 更新资产元数据
+   * @param {string} assetId
+   * @param {object} patch - 更新字段
+   * @returns {object} 更新后的记录
+   */
+  update(assetId, patch) {
+    const existing = this._assets.get(assetId);
+    if (!existing) {
+      throw new Error(`资产不存在: ${assetId}`);
+    }
+
+    if (patch.assetId && patch.assetId !== assetId) {
+      throw new Error('不允许修改 assetId');
+    }
+
+    if (patch.status && !VALID_REGISTRY_STATUSES.has(patch.status)) {
+      throw new Error(`status 必须为 ${[...VALID_REGISTRY_STATUSES].join('/')} 之一，当前值: ${patch.status}`);
+    }
+
+    if (patch.assetType && !VALID_ASSET_TYPES.has(patch.assetType)) {
+      throw new Error(`assetType 必须为 ${[...VALID_ASSET_TYPES].join('/')} 之一，当前值: ${patch.assetType}`);
+    }
+
+    const updated = {
+      ...existing,
+      ...patch,
+      assetId: existing.assetId, // 不可变
+      createdAt: existing.createdAt, // 不可变
+      updatedAt: new Date().toISOString(),
+      metadata: patch.metadata ? redactObject(patch.metadata) : existing.metadata,
+    };
+
+    if (patch.tags) {
+      updated.tags = Array.isArray(patch.tags) ? [...patch.tags] : existing.tags;
+    }
+
+    this._assets.set(assetId, updated);
+    this._appendToFile(updated);
+
+    return { ...updated, metadata: { ...updated.metadata } };
+  }
+
+  // ============================================================
+  // clear — 清空
+  // ============================================================
+
+  /** 清空注册表 */
+  clear() {
+    this._assets.clear();
+
+    if (this.storagePath) {
+      const dir = path.dirname(this.storagePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(this.storagePath, '', 'utf-8');
+    }
+  }
+
+  // ============================================================
+  // export — 导出
+  // ============================================================
+
+  /**
+   * 导出注册表
+   * @param {string} format - 'json' | 'ndjson'
+   * @returns {string}
+   */
+  export(format = 'json') {
+    const entries = [...this._assets.values()].map(r => ({ ...r, metadata: { ...r.metadata } }));
+    if (format === 'ndjson') {
+      return entries.map(e => JSON.stringify(e)).join('\n');
+    }
+    return JSON.stringify(entries, null, 2);
+  }
+
+  // ============================================================
+  // getLoadErrors — 坏行信息
+  // ============================================================
+
+  /** @returns {object[]} */
+  getLoadErrors() {
+    return this.loadErrors.map(e => ({ ...e }));
+  }
+
+  // ============================================================
+  // size getter
+  // ============================================================
+
+  /** @returns {number} */
+  get size() {
+    return this._assets.size;
+  }
+}
+
+// ============================================================
+// 工厂函数
+// ============================================================
+
+/**
+ * 创建资产注册表
+ * @param {object} [options]
+ * @returns {AssetRegistry}
+ */
+function createAssetRegistry(options) {
+  return new AssetRegistry(options);
+}
+
+module.exports = {
+  ASSET_REGISTRY_STATUSES,
+  VALID_REGISTRY_STATUSES,
+  AssetRegistry,
+  createAssetRegistry,
+};