@gong-ym/ai-spec-auto 0.2.3

package/src/config/config-layer.js

@@ -0,0 +1,343 @@
+const fs = require('fs');
+const path = require('path');
+const { DEFAULT_CONFIG } = require('./defaults');
+
+// ============================================================
+// 层定义 — 从低优先级到高优先级排列
+// ============================================================
+
+/**
+ * 配置层顺序（priority 越小越先合并，越后合并越优先覆盖）
+ *
+ * default → enterprise → global → manifest → agentProfile →
+ * workspace → project → team → policy → run → cli
+ */
+const CONFIG_LAYERS = Object.freeze([
+  { id: 'default',      name: '默认配置',     priority: 0 },
+  { id: 'enterprise',   name: '企业配置',     priority: 1 },
+  { id: 'global',       name: '全局配置',     priority: 2 },
+  { id: 'manifest',     name: 'Manifest 配置', priority: 3 },
+  { id: 'agentProfile', name: 'Agent Profile', priority: 4 },
+  { id: 'workspace',    name: '工作区配置',   priority: 5 },
+  { id: 'project',      name: '项目配置',     priority: 6 },
+  { id: 'team',         name: '团队配置',     priority: 7 },
+  { id: 'policy',       name: '策略配置',     priority: 8 },
+  { id: 'run',          name: '运行时配置',   priority: 9 },
+  { id: 'cli',          name: 'CLI 参数',     priority: 10 },
+]);
+
+const LAYER_IDS = Object.freeze(CONFIG_LAYERS.map((l) => l.id));
+
+// ============================================================
+// 只读字段 — 企业级安全底线，任何层不得覆盖
+// ============================================================
+
+const READONLY_FIELDS = Object.freeze([
+  'privacyPolicy.uploadSourceCode',
+  'privacyPolicy.uploadAbsolutePath',
+  'privacyPolicy.uploadUserName',
+  'privacyPolicy.uploadRawPrompt',
+  'privacyPolicy.uploadRawResponse',
+  'privacyPolicy.uploadFileContent',
+]);
+
+// ============================================================
+// 工具函数
+// ============================================================
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function deepMerge(...objects) {
+  const output = {};
+  for (const object of objects) {
+    if (!isPlainObject(object)) continue;
+    for (const [key, value] of Object.entries(object)) {
+      if (isPlainObject(value) && isPlainObject(output[key])) {
+        output[key] = deepMerge(output[key], value);
+      } else if (Array.isArray(value)) {
+        output[key] = [...value];
+      } else if (isPlainObject(value)) {
+        output[key] = deepMerge(value);
+      } else if (value !== undefined) {
+        output[key] = value;
+      }
+    }
+  }
+  return output;
+}
+
+function getNestedValue(obj, dottedPath) {
+  const parts = dottedPath.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (!isPlainObject(current)) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function setNestedValue(obj, dottedPath, value) {
+  const parts = dottedPath.split('.');
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!isPlainObject(current[parts[i]])) {
+      current[parts[i]] = {};
+    }
+    current = current[parts[i]];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+// ============================================================
+// LayerRegistry — 配置层注册表
+// ============================================================
+
+class LayerRegistry {
+  constructor() {
+    this._layers = new Map();
+    for (const layer of CONFIG_LAYERS) {
+      this._layers.set(layer.id, { ...layer });
+    }
+  }
+
+  /**
+   * 获取所有层（按优先级升序）
+   * @returns {Array<{id: string, name: string, priority: number}>}
+   */
+  getAll() {
+    return [...this._layers.values()].sort((a, b) => a.priority - b.priority);
+  }
+
+  /**
+   * 获取指定层
+   * @param {string} layerId
+   * @returns {{id: string, name: string, priority: number}|undefined}
+   */
+  get(layerId) {
+    return this._layers.get(layerId);
+  }
+
+  /**
+   * 检查层是否存在
+   * @param {string} layerId
+   * @returns {boolean}
+   */
+  has(layerId) {
+    return this._layers.has(layerId);
+  }
+
+  /**
+   * 获取层 ID 列表（按优先级升序）
+   * @returns {string[]}
+   */
+  getOrderedIds() {
+    return this.getAll().map((l) => l.id);
+  }
+}
+
+// ============================================================
+// 隐私策略强制覆盖
+// ============================================================
+
+function forcePrivacyPolicy(config) {
+  return deepMerge(config, {
+    privacyPolicy: {
+      uploadSourceCode: false,
+      uploadAbsolutePath: false,
+      uploadUserName: false,
+      uploadRawPrompt: false,
+      uploadRawResponse: false,
+      uploadFileContent: false,
+    },
+  });
+}
+
+// ============================================================
+// 只读字段保护
+// ============================================================
+
+/**
+ * 检查只读字段是否被覆盖
+ * @param {Object} defaultConfig - 默认配置
+ * @param {Object} mergedConfig - 合并后的配置
+ * @returns {{ ok: boolean, violations: string[] }}
+ */
+function checkReadonlyFields(defaultConfig, mergedConfig) {
+  const violations = [];
+
+  for (const field of READONLY_FIELDS) {
+    const defaultVal = getNestedValue(defaultConfig, field);
+    const mergedVal = getNestedValue(mergedConfig, field);
+
+    // 只在字段被显式设置且值不同时才算违规（undefined 表示字段未被设置）
+    if (
+      mergedVal !== undefined &&
+      defaultVal !== undefined &&
+      mergedVal !== defaultVal
+    ) {
+      violations.push(field);
+    }
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+// ============================================================
+// 冲突检测
+// ============================================================
+
+/**
+ * 检测层间配置冲突
+ * @param {Object} layerData - { layerId: configObj } 的映射
+ * @returns {Array<{ field: string, layers: string[], values: any[] }>}
+ */
+function detectConflicts(layerData) {
+  const conflicts = [];
+  const fieldLayerMap = new Map();
+
+  // 收集每个字段在哪些层被设置
+  for (const [layerId, config] of Object.entries(layerData)) {
+    if (!isPlainObject(config)) continue;
+    collectFields(config, '', layerId, fieldLayerMap);
+  }
+
+  // 检测被多个层设置的字段
+  for (const [field, layers] of fieldLayerMap) {
+    if (layers.length > 1) {
+      // 只有当值不同时才算冲突
+      const values = layers.map((l) => ({
+        layer: l.layerId,
+        value: l.value,
+      }));
+      const uniqueValues = new Set(values.map((v) => JSON.stringify(v.value)));
+      if (uniqueValues.size > 1) {
+        conflicts.push({
+          field,
+          layers: values.map((v) => v.layer),
+          values: values.map((v) => v.value),
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+function collectFields(obj, prefix, layerId, fieldLayerMap) {
+  for (const [key, value] of Object.entries(obj)) {
+    const fieldPath = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(value)) {
+      collectFields(value, fieldPath, layerId, fieldLayerMap);
+    } else {
+      if (!fieldLayerMap.has(fieldPath)) {
+        fieldLayerMap.set(fieldPath, []);
+      }
+      fieldLayerMap.get(fieldPath).push({ layerId, value });
+    }
+  }
+}
+
+// ============================================================
+// 配置合并 — 按层顺序合并并收集元数据
+// ============================================================
+
+/**
+ * 合并多层配置
+ * @param {Object} layerData - { layerId: configObj } 的映射
+ * @returns {{ config: Object, conflicts: Array, readonlyViolations: string[] }}
+ */
+function mergeConfigs(layerData) {
+  const registry = new LayerRegistry();
+  const orderedIds = registry.getOrderedIds();
+
+  // 按层顺序合并
+  const objects = [];
+  for (const layerId of orderedIds) {
+    const data = layerData[layerId];
+    if (isPlainObject(data)) {
+      objects.push(data);
+    }
+  }
+
+  let merged = deepMerge(...objects);
+
+  // 检测冲突
+  const conflicts = detectConflicts(layerData);
+
+  // 只读字段保护
+  const defaultConfig = layerData.default || DEFAULT_CONFIG;
+  const readonlyCheck = checkReadonlyFields(defaultConfig, merged);
+  const readonlyViolations = readonlyCheck.violations;
+
+  // 强制隐私策略
+  merged = forcePrivacyPolicy(merged);
+
+  return { config: merged, conflicts, readonlyViolations };
+}
+
+// ============================================================
+// 从文件加载企业/团队配置
+// ============================================================
+
+function readJsonIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    const wrapped = new Error(`配置文件解析失败：${filePath}。请检查 JSON 格式。`);
+    wrapped.code = 'VALIDATION_FAILED';
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}
+
+/**
+ * 从文件系统加载企业配置
+ * @param {string} rootDir
+ * @returns {Object|null}
+ */
+function loadEnterpriseConfig(rootDir) {
+  // 优先从项目内读取，再从全局读取
+  const localPath = path.join(rootDir, '.ai-spec', 'enterprise.json');
+  if (fs.existsSync(localPath)) return readJsonIfExists(localPath);
+
+  const globalPath = path.join(
+    require('os').homedir(),
+    '.ai-spec-auto',
+    'enterprise.json',
+  );
+  return readJsonIfExists(globalPath);
+}
+
+/**
+ * 从文件系统加载团队配置
+ * @param {string} rootDir
+ * @returns {Object|null}
+ */
+function loadTeamConfig(rootDir) {
+  const teamPath = path.join(rootDir, '.ai-spec', 'team.json');
+  return readJsonIfExists(teamPath);
+}
+
+// ============================================================
+// 导出
+// ============================================================
+
+module.exports = {
+  CONFIG_LAYERS,
+  LAYER_IDS,
+  READONLY_FIELDS,
+  LayerRegistry,
+  deepMerge,
+  mergeConfigs,
+  detectConflicts,
+  checkReadonlyFields,
+  forcePrivacyPolicy,
+  loadEnterpriseConfig,
+  loadTeamConfig,
+  readJsonIfExists,
+  getNestedValue,
+  setNestedValue,
+};

package/src/config/config-loader.js

@@ -0,0 +1,60 @@
+const os = require('os');
+const path = require('path');
+const { DEFAULT_CONFIG } = require('./defaults');
+const {
+  mergeConfigs,
+  loadEnterpriseConfig,
+  loadTeamConfig,
+  readJsonIfExists,
+} = require('./config-layer');
+
+function normalizeCliOptions(cliOptions = {}) {
+  const normalized = { ...cliOptions };
+  if (cliOptions.executor && !normalized.execution) {
+    normalized.execution = { executor: cliOptions.executor };
+    delete normalized.executor;
+  }
+  if (cliOptions.mode && !normalized.execution?.mode) {
+    normalized.execution = { ...(normalized.execution || {}), mode: cliOptions.mode };
+    delete normalized.mode;
+  }
+  return normalized;
+}
+
+class ConfigLoader {
+  async load(input = {}) {
+    const rootDir = path.resolve(input.rootDir || process.cwd());
+    const globalConfigPath =
+      input.globalConfigPath || path.join(os.homedir(), '.ai-spec-auto', 'config.json');
+
+    const enterpriseConfig = loadEnterpriseConfig(rootDir);
+    const globalConfig = readJsonIfExists(globalConfigPath);
+    const workspaceConfig = readJsonIfExists(path.join(rootDir, '.ai-spec', 'workspace.json'));
+    const projectConfig = readJsonIfExists(path.join(rootDir, '.ai-spec', 'project.json'));
+    const teamConfig = loadTeamConfig(rootDir);
+    const policyConfig = readJsonIfExists(path.join(rootDir, '.ai-spec', 'policy.json'));
+    const cliOptions = normalizeCliOptions(input.cliOptions || {});
+
+    const result = mergeConfigs({
+      default: DEFAULT_CONFIG,
+      enterprise: enterpriseConfig,
+      global: globalConfig,
+      manifest: input.manifestConfig,
+      agentProfile: input.agentProfile,
+      workspace: workspaceConfig,
+      project: projectConfig,
+      team: teamConfig,
+      policy: policyConfig,
+      run: input.runConfig,
+      cli: cliOptions,
+    });
+
+    return result.config;
+  }
+}
+
+module.exports = {
+  ConfigLoader,
+  deepMerge: require('./config-layer').deepMerge,
+  readJsonIfExists,
+};

package/src/config/defaults.js

@@ -0,0 +1,49 @@
+const DEFAULT_CONFIG = Object.freeze({
+  execution: {
+    mode: 'local-assisted',
+    executor: 'codex',
+    fallbackExecutors: ['cursor', 'claude-code'],
+  },
+  branchPolicy: {
+    autoCreateBranch: false,
+    autoCreateWorktree: false,
+    branchPrefix: 'ai/',
+    worktreeRoot: '.ai-spec/worktrees',
+    dirtyStrategy: 'block',
+  },
+  approvalPolicy: {
+    beforeCodeChange: false,
+    beforeTestRun: false,
+    beforeCommit: true,
+    beforePush: true,
+    beforeMerge: true,
+    highRiskAlwaysManual: true,
+  },
+  privacyPolicy: {
+    uploadSourceCode: false,
+    uploadAbsolutePath: false,
+    uploadUserName: false,
+    uploadRawPrompt: false,
+    uploadRawResponse: false,
+    uploadFileContent: false,
+    allowRelativePath: true,
+    allowFailureSummary: true,
+    allowTestSummary: true,
+  },
+  tokenBudget: {
+    enabled: true,
+    maxInputTokens: 120000,
+    maxOutputTokens: 16000,
+    maxTotalTokens: 150000,
+    warningThreshold: 0.8,
+  },
+  scanPolicy: {
+    maxDepth: 5,
+    includeLockfileFacts: false,
+    explain: false,
+  },
+});
+
+module.exports = {
+  DEFAULT_CONFIG,
+};

package/src/connectors/hub/asset-package.js

@@ -0,0 +1,72 @@
+const crypto = require('crypto');
+const path = require('path');
+
+const ASSET_TYPE_MAP = {
+  rule: 'rule',
+  rules: 'rule',
+  skill: 'skill',
+  skills: 'skill',
+  role: 'agentProfile',
+  agent: 'agentProfile',
+  agentProfile: 'agentProfile',
+  profile: 'agentProfile',
+  workflow: 'workflow',
+  flow: 'workflow',
+  hook: 'hook',
+  command: 'command',
+};
+
+function sha256Json(value) {
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(value || {})).digest('hex')}`;
+}
+
+function assertRelativePath(relPath) {
+  const normalized = path.posix.normalize(String(relPath || '').replace(/\\/g, '/'));
+  if (!normalized || path.isAbsolute(relPath) || normalized === '..' || normalized.startsWith('../')) {
+    throw new Error(`资产文件路径非法：${relPath}`);
+  }
+  return normalized;
+}
+
+function normalizeAssetType(value) {
+  return ASSET_TYPE_MAP[String(value || '').trim()] || String(value || 'rule');
+}
+
+function normalizeAssetFiles(asset = {}) {
+  const files = Array.isArray(asset.files)
+    ? asset.files
+    : Array.isArray(asset.generatedFiles)
+      ? asset.generatedFiles
+      : asset.installPath || asset.path
+        ? [{ path: asset.installPath || asset.path, checksum: asset.checksum }]
+        : [];
+  return files.map((file) => ({
+    path: assertRelativePath(file.path || file.installPath),
+    checksum: file.checksum || asset.checksum || '',
+  }));
+}
+
+function normalizeAssetPackage(asset = {}, options = {}) {
+  const assetId = asset.assetId || asset.slug || asset.id || '';
+  const assetType = normalizeAssetType(asset.assetType || asset.kind || asset.type);
+  const files = normalizeAssetFiles(asset);
+  return {
+    ...asset,
+    assetId,
+    assetType,
+    name: asset.name || asset.displayName || assetId,
+    version: asset.version || '0.1.0',
+    source: asset.source || options.source || 'skill-q-platform',
+    checksum: asset.checksum || sha256Json({ assetId, assetType, files }),
+    compatibility: asset.compatibility || options.compatibility || {},
+    files,
+    metadata: asset.metadata || {},
+  };
+}
+
+module.exports = {
+  assertRelativePath,
+  normalizeAssetFiles,
+  normalizeAssetPackage,
+  normalizeAssetType,
+};

package/src/connectors/hub/asset-usage-feedback.js

@@ -0,0 +1,46 @@
+const crypto = require('crypto');
+
+function hash(value, length = 12) {
+  return crypto.createHash('sha256').update(String(value || '')).digest('hex').slice(0, length);
+}
+
+function normalizeStatus(value) {
+  const text = String(value || '').trim();
+  if (['success', 'passed', 'pass', 'ok', '成功', '通过'].includes(text)) return 'success';
+  if (['failure', 'failed', 'fail', 'error', '失败'].includes(text)) return 'failure';
+  if (['blocked', '阻塞'].includes(text)) return 'blocked';
+  return 'unknown';
+}
+
+function normalizeAssetUsageFeedback(input = {}) {
+  const timestamp = input.timestamp || new Date().toISOString();
+  const assetId = input.assetId || input.asset?.assetId || input.asset?.slug || '';
+  const assetType = input.assetType || input.asset?.assetType || input.asset?.kind || 'rule';
+  const runId = input.runId || '';
+  return {
+    feedbackId: input.feedbackId || `fb_${hash(`${runId}:${assetId}:${timestamp}`)}`,
+    runId,
+    projectId: input.projectId || '',
+    assetId,
+    assetType,
+    status: normalizeStatus(input.status || input.result?.status),
+    metrics: {
+      ...(input.metrics && typeof input.metrics === 'object' ? input.metrics : {}),
+      adopted: input.metrics?.adopted ?? input.adopted ?? true,
+      hookBlocked: input.metrics?.hookBlocked ?? false,
+      testPassed: input.metrics?.testPassed ?? input.result?.success === true,
+    },
+    timestamp,
+  };
+}
+
+function buildUsageFeedbackList(input = {}) {
+  const assets = Array.isArray(input.assetsUsed) ? input.assetsUsed : [];
+  if (assets.length === 0) return [normalizeAssetUsageFeedback(input)];
+  return assets.map((asset) => normalizeAssetUsageFeedback({ ...input, asset }));
+}
+
+module.exports = {
+  buildUsageFeedbackList,
+  normalizeAssetUsageFeedback,
+};

package/src/connectors/hub/hub-connector.js

@@ -0,0 +1,44 @@
+const { HubClient } = require('../../hub/hub-client');
+const { normalizeAssetPackage } = require('./asset-package');
+const { buildUsageFeedbackList } = require('./asset-usage-feedback');
+
+class HubConnector {
+  constructor(options = {}) {
+    this.hubClient = options.hubClient || new HubClient(options);
+  }
+
+  async searchAssets(input = {}) {
+    const hubUrl = this.hubClient.resolveHubUrl(input.hubUrl);
+    if (!hubUrl) {
+      throw new Error('未配置 Hub URL，无法搜索资产。');
+    }
+    const params = new URLSearchParams();
+    if (input.query || input.q) params.set('q', input.query || input.q);
+    if (input.assetType || input.kind) params.set('kind', input.assetType || input.kind);
+    const url = `${hubUrl}/api/hub/search?${params.toString()}`;
+    const data = await fetch(url).then(async (response) => {
+      const body = await response.json();
+      if (!response.ok || body?.success === false) {
+        throw new Error(body?.error?.message || body?.message || `Hub 搜索失败：HTTP ${response.status}`);
+      }
+      return Object.prototype.hasOwnProperty.call(body || {}, 'success') ? body.data : body;
+    });
+    const items = Array.isArray(data?.items) ? data.items : Array.isArray(data) ? data : [];
+    return {
+      ...data,
+      items: items.map((item) => normalizeAssetPackage(item)),
+    };
+  }
+
+  normalizeAssetPackage(asset, options = {}) {
+    return normalizeAssetPackage(asset, options);
+  }
+
+  buildUsageFeedback(input = {}) {
+    return buildUsageFeedbackList(input);
+  }
+}
+
+module.exports = {
+  HubConnector,
+};

package/src/connectors/hub/index.js

@@ -0,0 +1,21 @@
+const {
+  assertRelativePath,
+  normalizeAssetFiles,
+  normalizeAssetPackage,
+  normalizeAssetType,
+} = require('./asset-package');
+const {
+  buildUsageFeedbackList,
+  normalizeAssetUsageFeedback,
+} = require('./asset-usage-feedback');
+const { HubConnector } = require('./hub-connector');
+
+module.exports = {
+  HubConnector,
+  assertRelativePath,
+  buildUsageFeedbackList,
+  normalizeAssetFiles,
+  normalizeAssetPackage,
+  normalizeAssetType,
+  normalizeAssetUsageFeedback,
+};

package/src/connectors/visual/evidence-report.js

@@ -0,0 +1,49 @@
+const STATUS_MAP = {
+  success: 'success',
+  passed: 'success',
+  pass: 'success',
+  ok: 'success',
+  failure: 'failure',
+  failed: 'failure',
+  fail: 'failure',
+  error: 'failure',
+  blocked: 'blocked',
+  通过: 'success',
+  成功: 'success',
+  失败: 'failure',
+  阻塞: 'blocked',
+  待执行: 'unknown',
+};
+
+function normalizeFinalStatus(value) {
+  return STATUS_MAP[String(value || '').trim()] || 'unknown';
+}
+
+function normalizeChangedFiles(changedFiles = []) {
+  return (Array.isArray(changedFiles) ? changedFiles : []).map((file) => ({
+    path: String(file.path || ''),
+    changeType: file.changeType || file.action || 'modify',
+    summary: file.summary || file.description || '',
+  })).filter((file) => file.path);
+}
+
+function normalizeEvidenceReport(input = {}) {
+  return {
+    ...input,
+    runId: input.runId || '',
+    projectId: input.projectId || '',
+    taskId: input.taskId || '',
+    specId: input.specId || '',
+    changedFiles: normalizeChangedFiles(input.changedFiles),
+    testResults: Array.isArray(input.testResults) ? input.testResults : [],
+    hookResults: Array.isArray(input.hookResults) ? input.hookResults : [],
+    repairResults: Array.isArray(input.repairResults) ? input.repairResults : [],
+    reviewResults: Array.isArray(input.reviewResults) ? input.reviewResults : [],
+    finalStatus: normalizeFinalStatus(input.finalStatus || input.status),
+  };
+}
+
+module.exports = {
+  normalizeEvidenceReport,
+  normalizeFinalStatus,
+};

package/src/connectors/visual/index.js

@@ -0,0 +1,15 @@
+const { normalizeEvidenceReport, normalizeFinalStatus } = require('./evidence-report');
+const { VisualFailureQueue, defaultVisualQueueDir } = require('./queue');
+const { normalizeRunEvent, normalizeSeverity, normalizeStatus } = require('./run-event');
+const { VisualConnector } = require('./visual-connector');
+
+module.exports = {
+  VisualConnector,
+  VisualFailureQueue,
+  defaultVisualQueueDir,
+  normalizeEvidenceReport,
+  normalizeFinalStatus,
+  normalizeRunEvent,
+  normalizeSeverity,
+  normalizeStatus,
+};