@gong-ym/ai-spec-auto 0.2.3

package/src/connectors/visual/queue.js

@@ -0,0 +1,41 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function defaultVisualQueueDir(homeDir = os.homedir()) {
+  return path.join(homeDir, '.ai-spec-auto', 'visual-queue');
+}
+
+function sanitizeName(value) {
+  return String(value || 'event').replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 80);
+}
+
+class VisualFailureQueue {
+  constructor(options = {}) {
+    this.queueDir = options.queueDir || defaultVisualQueueDir(options.homeDir);
+  }
+
+  enqueue(record = {}) {
+    fs.mkdirSync(this.queueDir, { recursive: true });
+    const now = new Date().toISOString();
+    const type = sanitizeName(record.type || record.payload?.eventType || record.payload?.type);
+    const id = sanitizeName(record.payload?.eventId || record.payload?.runId || Date.now());
+    const filePath = path.join(this.queueDir, `${now.replace(/[:.]/g, '-')}-${type}-${id}.json`);
+    const entry = {
+      schemaVersion: '1.0.0',
+      queuedAt: now,
+      type: record.type || 'run-event',
+      endpoint: record.endpoint || '',
+      reason: record.reason || '',
+      code: record.code || 'VISUAL_REPORT_FAILED',
+      payload: record.payload || {},
+    };
+    fs.writeFileSync(filePath, `${JSON.stringify(entry, null, 2)}\n`, 'utf8');
+    return { filePath, entry };
+  }
+}
+
+module.exports = {
+  VisualFailureQueue,
+  defaultVisualQueueDir,
+};

package/src/connectors/visual/run-event.js

@@ -0,0 +1,81 @@
+const crypto = require('crypto');
+
+const STATUS_MAP = {
+  success: 'success',
+  passed: 'success',
+  pass: 'success',
+  ok: 'success',
+  running: 'running',
+  pending: 'running',
+  skipped: 'skipped',
+  skip: 'skipped',
+  blocked: 'blocked',
+  failure: 'failure',
+  failed: 'failure',
+  fail: 'failure',
+  error: 'failure',
+  通过: 'success',
+  成功: 'success',
+  失败: 'failure',
+  阻塞: 'blocked',
+  待执行: 'unknown',
+};
+
+const SEVERITY_MAP = {
+  info: 'info',
+  warn: 'warn',
+  warning: 'warn',
+  error: 'error',
+  failed: 'error',
+  blocking: 'blocking',
+  blocked: 'blocking',
+};
+
+function hash(value, length = 12) {
+  return crypto.createHash('sha256').update(String(value || '')).digest('hex').slice(0, length);
+}
+
+function normalizeStatus(value) {
+  return STATUS_MAP[String(value || '').trim()] || 'unknown';
+}
+
+function normalizeSeverity(value) {
+  return SEVERITY_MAP[String(value || '').trim()] || 'info';
+}
+
+function normalizeRunEvent(input = {}) {
+  const timestamp = input.timestamp || input.occurredAt || input.createdAt || new Date().toISOString();
+  const eventType = input.eventType || input.type || 'runtime.event';
+  const status = normalizeStatus(input.status || input.state);
+  const severity = normalizeSeverity(input.severity || input.level || (status === 'failure' ? 'error' : status));
+  const metadata = {
+    ...(input.metadata && typeof input.metadata === 'object' ? input.metadata : {}),
+    ...(input.payload && typeof input.payload === 'object' ? input.payload : {}),
+  };
+  const eventId = input.eventId || `evt_${hash(`${input.runId || 'run'}:${eventType}:${timestamp}`)}`;
+
+  return {
+    ...input,
+    eventId,
+    runId: input.runId || '',
+    projectId: input.projectId || '',
+    eventType,
+    stage: input.stage || input.state || 'unknown',
+    status,
+    severity,
+    message: input.message || input.summary || '',
+    timestamp,
+    metadata,
+
+    // 兼容旧版 Visual Collector。
+    type: input.type || eventType,
+    level: input.level || severity,
+    occurredAt: input.occurredAt || timestamp,
+  };
+}
+
+module.exports = {
+  normalizeRunEvent,
+  normalizeSeverity,
+  normalizeStatus,
+};

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

@@ -0,0 +1,77 @@
+const { VisualClient } = require('../../visual/visual-client');
+const { normalizeEvidenceReport } = require('./evidence-report');
+const { normalizeRunEvent } = require('./run-event');
+const { VisualFailureQueue } = require('./queue');
+
+function skipped(message, code) {
+  return { ok: false, skipped: true, warning: message, code };
+}
+
+class VisualConnector {
+  constructor(options = {}) {
+    this.client = options.client || options.visualClient || new VisualClient(options);
+    this.queue = options.queue || new VisualFailureQueue(options);
+  }
+
+  async reportRunEvent(payload = {}, options = {}) {
+    return this.report('run-event', normalizeRunEvent(payload), options);
+  }
+
+  async reportEvidenceReport(payload = {}, options = {}) {
+    return this.report('evidence-report', normalizeEvidenceReport(payload), {
+      endpoint: '/api/collector/evidence-report',
+      ...options,
+    });
+  }
+
+  async report(type, payload = {}, options = {}) {
+    if (options.enabled === false) {
+      return skipped('Visual 上报开关已关闭，已跳过。', 'VISUAL_DISABLED');
+    }
+    const visualUrl = options.visualUrl || payload.visualUrl || '';
+    if (!visualUrl) {
+      return skipped('未配置 Visual URL，已跳过运行态上报。', 'VISUAL_URL_MISSING');
+    }
+    const endpoint = options.endpoint || '/api/collector/run-event';
+    let safePayload = payload;
+    try {
+      if (this.client.privacyFilter && typeof this.client.privacyFilter.filter === 'function') {
+        safePayload = this.client.privacyFilter.filter(payload);
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        skipped: true,
+        queued: false,
+        warning: `Visual 上报因隐私策略被拦截：${error.message}`,
+        code: error.code || 'PRIVACY_POLICY_VIOLATED',
+      };
+    }
+    try {
+      const data = type === 'run-event'
+        ? await this.client.sendRunEvent(safePayload, { visualUrl })
+        : await this.client.post(endpoint, safePayload, { visualUrl });
+      return { ok: true, skipped: false, data, warning: null };
+    } catch (error) {
+      const queued = this.queue.enqueue({
+        type,
+        endpoint,
+        payload: safePayload,
+        reason: error.message,
+        code: error.code || 'VISUAL_REPORT_FAILED',
+      });
+      return {
+        ok: false,
+        skipped: true,
+        queued: true,
+        queueFile: queued.filePath,
+        warning: `Visual 上报失败，已写入失败队列：${error.message}`,
+        code: error.code || 'VISUAL_REPORT_FAILED',
+      };
+    }
+  }
+}
+
+module.exports = {
+  VisualConnector,
+};

package/src/context/context-budget.js

@@ -0,0 +1,59 @@
+const { createIssue, normalizeTokenBudget } = require('./types');
+
+class ContextBudget {
+  constructor(tokenBudget = {}) {
+    this.tokenBudget = normalizeTokenBudget(tokenBudget);
+  }
+
+  estimateTextTokens(text) {
+    if (!text) return 0;
+    return Math.ceil(String(text).length / 4);
+  }
+
+  evaluate(loadedAssets = [], tokenBudget = this.tokenBudget) {
+    const normalizedBudget = normalizeTokenBudget(tokenBudget);
+    const warnings = [];
+    const errors = [];
+    let inputTokens = 0;
+
+    for (const asset of loadedAssets) {
+      const tokenEstimate = Number.isFinite(asset.tokenEstimate)
+        ? asset.tokenEstimate
+        : this.estimateTextTokens(asset.content || '');
+      asset.tokenEstimate = tokenEstimate;
+      inputTokens += tokenEstimate;
+    }
+
+    if (inputTokens > normalizedBudget.warningThreshold) {
+      warnings.push(createIssue(
+        'warning',
+        'CONTEXT_TOKEN_WARNING_THRESHOLD_EXCEEDED',
+        `Context token 估算 ${inputTokens} 已超过 warningThreshold ${normalizedBudget.warningThreshold}`,
+        '请减少阶段资产数量或下调加载规则',
+      ));
+    }
+
+    if (inputTokens > normalizedBudget.maxInputTokens) {
+      errors.push(createIssue(
+        'error',
+        'CONTEXT_TOKEN_BUDGET_EXCEEDED',
+        `Context token 估算 ${inputTokens} 已超过 maxInputTokens ${normalizedBudget.maxInputTokens}`,
+        '请减少加载资产或提高预算上限',
+      ));
+    }
+
+    return {
+      tokenEstimate: {
+        inputTokens,
+        maxInputTokens: normalizedBudget.maxInputTokens,
+        warning: inputTokens > normalizedBudget.warningThreshold,
+      },
+      warnings,
+      errors,
+    };
+  }
+}
+
+module.exports = {
+  ContextBudget,
+};

package/src/context/context-builder.js

@@ -0,0 +1,285 @@
+const fs = require('fs');
+const path = require('path');
+const { GlobalCache } = require('../cache/global-cache');
+const { getProjectFiles, readJsonFile, readProjectState } = require('../project/project-files');
+const { ContextBudget } = require('./context-budget');
+const { ContextLoader, hasContentField } = require('./context-loader');
+const { ContextPlanner } = require('./context-planner');
+const {
+  CONTEXT_PRIVACY_FLAGS,
+  CONTEXT_SCHEMA_VERSION,
+  assertValidStage,
+  createIssue,
+  normalizeContextOptions,
+  normalizeTokenBudget,
+} = require('./types');
+
+function readRequiredState(rootDir) {
+  const state = readProjectState(rootDir);
+  const required = [
+    ['project', '.ai-spec/project.json'],
+    ['lock', '.ai-spec/ai-spec.lock.json'],
+    ['registry', '.agents/registry.index.json'],
+    ['contextIndex', '.ai-spec/context-index.json'],
+  ];
+  for (const [key, label] of required) {
+    if (!state[key]) {
+      throw new Error(`缺少 ${label}，无法构建 ContextBundle`);
+    }
+  }
+  return state;
+}
+
+function sanitizeProject(project = {}) {
+  return {
+    projectId: project.projectId || '',
+    projectName: project.projectName || '',
+    projectType: project.projectType || '',
+    techProfile: project.techProfile || {},
+    manifest: project.manifest || {},
+  };
+}
+
+function readWorkspace(rootDir) {
+  const workspacePath = path.join(rootDir, '.ai-spec/workspace.json');
+  if (!fs.existsSync(workspacePath)) return null;
+  return readJsonFile(workspacePath);
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function redactKnownAbsolutePaths(text, rootDir, cacheRootDir) {
+  let result = String(text || '');
+  for (const [absolutePath, replacement] of [
+    [rootDir, '.'],
+    [cacheRootDir, '~/.ai-spec-auto'],
+  ]) {
+    if (absolutePath) {
+      result = result.replace(new RegExp(escapeRegExp(absolutePath), 'g'), replacement);
+    }
+  }
+  return result;
+}
+
+function sanitizeRelativeValue(value, rootDir) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeRelativeValue(item, rootDir));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeRelativeValue(item, rootDir)]));
+  }
+  if (typeof value === 'string' && path.isAbsolute(value)) {
+    const relative = path.relative(rootDir, value);
+    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+      return relative || '.';
+    }
+    return '<absolute-path-redacted>';
+  }
+  return value;
+}
+
+function assetIdentity(asset) {
+  return `${asset.kind || ''}:${asset.slug || ''}:${asset.version || ''}`;
+}
+
+function createLockAssetMap(lockFile = {}) {
+  const result = new Map();
+  const lockAssets = [
+    ...(Array.isArray(lockFile.assets) ? lockFile.assets : []),
+    ...(Array.isArray(lockFile.agentProfiles) ? lockFile.agentProfiles.map((item) => ({ ...item, kind: item.kind || 'agent-profile' })) : []),
+  ];
+  for (const asset of lockAssets) {
+    const kind = asset.kind || 'asset';
+    result.set(assetIdentity({ ...asset, kind }), { ...asset, kind });
+  }
+  return result;
+}
+
+function applyLockToPlan(plan, lockFile) {
+  const lockByIdentity = createLockAssetMap(lockFile);
+  const warnings = [];
+  if (lockByIdentity.size === 0) {
+    warnings.push(createIssue(
+      'warning',
+      'CONTEXT_LOCK_ASSETS_EMPTY',
+      '当前 lock.assets 为空，阶段没有匹配资产，ContextBuilder 不加载 registry 中的资产正文',
+      '请先执行 ai-spec-auto sync . 或重新生成 lock',
+    ));
+    return {
+      assetsToLoad: [],
+      warnings,
+    };
+  }
+
+  const assetsToLoad = [];
+  for (const asset of plan.assetsToLoad) {
+    const lockAsset = lockByIdentity.get(assetIdentity(asset));
+    if (!lockAsset) {
+      warnings.push(createIssue(
+        'warning',
+        'CONTEXT_REGISTRY_ASSET_NOT_IN_LOCK',
+        `registry 资产未出现在 lock 中，已跳过：${asset.kind}:${asset.slug || asset.checksum}`,
+        '请执行 ai-spec-auto sync . 保持 lock 与 registry 一致',
+      ));
+      continue;
+    }
+    if (lockAsset.checksum !== asset.checksum) {
+      warnings.push(createIssue(
+        'warning',
+        'CONTEXT_REGISTRY_LOCK_CHECKSUM_MISMATCH',
+        `registry 与 lock checksum 不一致，已跳过：${asset.kind}:${asset.slug || asset.checksum}`,
+        '请执行 ai-spec-auto sync . 修复索引',
+      ));
+      continue;
+    }
+    assetsToLoad.push({
+      ...asset,
+      checksum: lockAsset.checksum,
+      version: lockAsset.version || asset.version || '',
+    });
+  }
+
+  if (assetsToLoad.length === 0) {
+    warnings.push(createIssue(
+      'warning',
+      'CONTEXT_ASSET_NOT_MATCHED',
+      `阶段 ${plan.stage} 没有匹配资产`,
+      '请确认 context-index 阶段规则、registry 和 lock 是否一致',
+    ));
+  }
+
+  return {
+    assetsToLoad,
+    warnings,
+  };
+}
+
+function mergeIssueArrays(...groups) {
+  return groups.flat().filter(Boolean);
+}
+
+function sanitizeLoadedAssets(loadedAssets, rootDir, cacheRootDir) {
+  return loadedAssets.map((asset) => {
+    const content = redactKnownAbsolutePaths(asset.content || '', rootDir, cacheRootDir);
+    return {
+      ...asset,
+      content,
+      contentLength: content.length,
+      tokenEstimate: undefined,
+    };
+  });
+}
+
+class ContextBuilder {
+  constructor(options = {}) {
+    this.globalCache = options.globalCache || new GlobalCache(options.cache || {});
+    this.contextPlanner = options.contextPlanner || new ContextPlanner();
+    this.contextLoader = options.contextLoader || new ContextLoader({ globalCache: this.globalCache });
+  }
+
+  async buildContext(input = {}) {
+    const rootDir = path.resolve(input.rootDir || process.cwd());
+    const stage = input.stage || 'planning';
+    assertValidStage(stage);
+    const options = normalizeContextOptions(input.options || {});
+    const tokenBudget = normalizeTokenBudget(input.tokenBudget || {});
+
+    if (input.cache && input.cache.rootDir) {
+      this.globalCache = new GlobalCache(input.cache);
+      this.contextLoader = new ContextLoader({ globalCache: this.globalCache });
+    }
+
+    const state = readRequiredState(rootDir);
+    const projectFiles = getProjectFiles(rootDir);
+    if (hasContentField(state.registry)) {
+      throw new Error('registry.index.json 不允许包含完整 content，ContextBuilder 已阻断加载');
+    }
+    const workspace = fs.existsSync(path.join(rootDir, '.ai-spec/workspace.json'))
+      ? sanitizeRelativeValue(readWorkspace(rootDir), rootDir)
+      : null;
+    const warnings = [];
+    const errors = [];
+
+    if (state.policy?.privacyPolicy) {
+      for (const field of ['uploadSourceCode', 'uploadRawPrompt', 'uploadRawResponse', 'uploadAbsolutePath', 'uploadFileContent']) {
+        if (state.policy.privacyPolicy[field] === true) {
+          warnings.push(createIssue(
+            'warning',
+            'CONTEXT_PRIVACY_POLICY_WARNING',
+            `隐私配置 ${field} 为 true，ContextBundle 仍会强制关闭对应内容`,
+            '请将该字段设置为 false',
+          ));
+        }
+      }
+    }
+
+    const plan = this.contextPlanner.plan({
+      stage,
+      contextIndex: state.contextIndex,
+      registryIndex: state.registry,
+      lockFile: state.lock,
+      targetPackages: input.targetPackages || [],
+    });
+    const lockedPlan = applyLockToPlan(plan, state.lock);
+
+    let loaderResult = { loadedAssets: [], warnings: [], errors: [] };
+    if (lockedPlan.assetsToLoad.length > 0) {
+      loaderResult = this.contextLoader.loadAssets(lockedPlan.assetsToLoad, {
+        allowMissingOptionalAssets: options.allowMissingOptionalAssets,
+      });
+    }
+
+    const loadedAssets = sanitizeLoadedAssets(loaderResult.loadedAssets, rootDir, this.globalCache.rootDir);
+    const budget = new ContextBudget(tokenBudget);
+    const budgetResult = budget.evaluate(loadedAssets, tokenBudget);
+
+    return {
+      schemaVersion: CONTEXT_SCHEMA_VERSION,
+      stage,
+      project: sanitizeProject(state.project),
+      workspace,
+      loadedAssets,
+      overlays: [],
+      sharedContracts: Array.isArray(state.contextIndex.sharedContracts) ? state.contextIndex.sharedContracts : [],
+      stageLoadRule: plan.stageLoadRule,
+      tokenEstimate: budgetResult.tokenEstimate,
+      privacy: { ...CONTEXT_PRIVACY_FLAGS },
+      warnings: mergeIssueArrays(
+        warnings,
+        plan.warnings || [],
+        lockedPlan.warnings,
+        loaderResult.warnings,
+        budgetResult.warnings,
+      ),
+      errors: mergeIssueArrays(
+        errors,
+        loaderResult.errors,
+        budgetResult.errors,
+      ),
+      ...(options.explain ? {
+        explain: {
+          reasons: plan.reasons,
+          files: {
+            project: path.relative(rootDir, projectFiles.project),
+            lock: path.relative(rootDir, projectFiles.lock),
+            registry: path.relative(rootDir, projectFiles.registry),
+            contextIndex: path.relative(rootDir, projectFiles.contextIndex),
+          },
+        },
+      } : {}),
+    };
+  }
+}
+
+async function buildContext(input) {
+  const options = input && input.cache ? { cache: input.cache } : {};
+  return new ContextBuilder(options).buildContext(input || {});
+}
+
+module.exports = {
+  ContextBuilder,
+  applyLockToPlan,
+  buildContext,
+};

package/src/context/context-loader.js

@@ -0,0 +1,116 @@
+const fs = require('fs');
+const path = require('path');
+const { GlobalCache } = require('../cache/global-cache');
+const { safeJsonHash, sha256File } = require('../security/checksum');
+const { ContextBudget } = require('./context-budget');
+const { createIssue } = require('./types');
+
+const SENSITIVE_CONTENT_RE = /(BEGIN (RSA|DSA|EC|OPENSSH)? ?PRIVATE KEY|AKIA[0-9A-Z]{16}|api[_-]?key\s*[:=]|secret\s*[:=]|password\s*[:=]|token\s*[:=])/i;
+
+function hasContentField(value) {
+  if (!value || typeof value !== 'object') return false;
+  if (Object.prototype.hasOwnProperty.call(value, 'content')) return true;
+  if (Array.isArray(value)) return value.some(hasContentField);
+  return Object.values(value).some(hasContentField);
+}
+
+function issueMessage(asset) {
+  return `${asset.kind || 'asset'}:${asset.slug || asset.checksum || ''}`;
+}
+
+class ContextLoader {
+  constructor(options = {}) {
+    this.globalCache = options.globalCache || new GlobalCache(options);
+    this.contextBudget = options.contextBudget || new ContextBudget();
+  }
+
+  getContentPath(asset) {
+    if (!asset.checksum) {
+      throw new Error(`资产缺少 checksum，无法加载：${issueMessage(asset)}`);
+    }
+    if (asset.kind === 'agent-profile') {
+      const jsonProfilePath = path.join(this.globalCache.agentProfilesDir, asset.checksum, 'content.json');
+      if (fs.existsSync(jsonProfilePath)) return jsonProfilePath;
+      const profilePath = path.join(this.globalCache.agentProfilesDir, asset.checksum, 'content.md');
+      if (fs.existsSync(profilePath)) return profilePath;
+      const legacyProfilePath = path.join(this.globalCache.agentProfilesDir, `${asset.slug || 'unknown'}@${asset.version || 'latest'}.json`);
+      if (fs.existsSync(legacyProfilePath)) return legacyProfilePath;
+    }
+    return this.globalCache.getAssetContentPath(asset.checksum);
+  }
+
+  loadAssets(assetsToLoad = [], options = {}) {
+    const allowMissingOptionalAssets = options.allowMissingOptionalAssets !== false;
+    const loadedAssets = [];
+    const warnings = [];
+    const errors = [];
+
+    for (const asset of assetsToLoad) {
+      if (hasContentField(asset)) {
+        throw new Error(`registry.index.json 不允许包含完整 content：${issueMessage(asset)}`);
+      }
+
+      const required = asset.required === true;
+      const contentPath = this.getContentPath(asset);
+      if (!fs.existsSync(contentPath)) {
+        const message = required
+          ? `必需资产缓存缺失：${issueMessage(asset)}`
+          : `可选资产缓存缺失：${issueMessage(asset)}`;
+        const item = createIssue(
+          required ? 'error' : 'warning',
+          required ? 'CONTEXT_REQUIRED_ASSET_CACHE_MISSING' : 'CONTEXT_OPTIONAL_ASSET_CACHE_MISSING',
+          message,
+          '请先执行 ai-spec-auto sync .',
+        );
+        if (required || !allowMissingOptionalAssets) {
+          errors.push(item);
+          throw new Error(message);
+        }
+        warnings.push(item);
+        continue;
+      }
+
+      const isHubAgentProfileJson = asset.kind === 'agent-profile' &&
+        path.basename(contentPath) === 'content.json' &&
+        path.basename(path.dirname(contentPath)) === asset.checksum;
+      const actualChecksum = isHubAgentProfileJson
+        ? safeJsonHash(JSON.parse(fs.readFileSync(contentPath, 'utf8')))
+        : sha256File(contentPath);
+      if (actualChecksum !== asset.checksum) {
+        throw new Error(`资产 checksum 不一致：${issueMessage(asset)}，期望 ${asset.checksum}，实际 ${actualChecksum}`);
+      }
+
+      const content = fs.readFileSync(contentPath, 'utf8');
+      if (SENSITIVE_CONTENT_RE.test(content)) {
+        warnings.push(createIssue(
+          'warning',
+          'CONTEXT_ASSET_SENSITIVE_CONTENT',
+          `资产疑似包含敏感内容：${issueMessage(asset)}`,
+          '请检查缓存资产来源，避免把密钥写入标准资产',
+        ));
+      }
+
+      loadedAssets.push({
+        kind: asset.kind || 'asset',
+        slug: asset.slug || '',
+        version: asset.version || '',
+        checksum: asset.checksum,
+        source: 'global-cache',
+        content,
+        contentLength: content.length,
+        tokenEstimate: this.contextBudget.estimateTextTokens(content),
+      });
+    }
+
+    return {
+      loadedAssets,
+      warnings,
+      errors,
+    };
+  }
+}
+
+module.exports = {
+  ContextLoader,
+  hasContentField,
+};