@gong-ym/ai-spec-auto 0.2.3

package/src/context/context-planner.js

@@ -0,0 +1,158 @@
+const {
+  DEFAULT_STAGE_LOAD_RULES,
+  assertValidStage,
+  createIssue,
+} = require('./types');
+
+const REGISTRY_GROUP_KIND = {
+  rules: 'rule',
+  skills: 'skill',
+  agentProfiles: 'agent-profile',
+  flows: 'flow',
+  roles: 'role',
+};
+
+function cloneRule(rule) {
+  return {
+    stage: rule.stage,
+    loadKinds: Array.isArray(rule.loadKinds) ? [...rule.loadKinds] : [],
+    requiredAgents: Array.isArray(rule.requiredAgents) ? [...rule.requiredAgents] : [],
+    maxAssets: Number.isFinite(rule.maxAssets) && rule.maxAssets > 0 ? rule.maxAssets : 1,
+  };
+}
+
+function getDefaultStageRule(stage) {
+  const rule = DEFAULT_STAGE_LOAD_RULES.find((item) => item.stage === stage);
+  return cloneRule(rule || DEFAULT_STAGE_LOAD_RULES[0]);
+}
+
+function resolveStageRule(stage, contextIndex = {}) {
+  const fileRule = (contextIndex.stageLoadRules || []).find((item) => item.stage === stage);
+  const baseRule = fileRule || getDefaultStageRule(stage);
+  const fallback = getDefaultStageRule(stage);
+  return {
+    stage,
+    loadKinds: Array.isArray(baseRule.loadKinds) && baseRule.loadKinds.length > 0
+      ? [...baseRule.loadKinds]
+      : fallback.loadKinds,
+    requiredAgents: Array.isArray(baseRule.requiredAgents)
+      ? [...baseRule.requiredAgents]
+      : fallback.requiredAgents,
+    maxAssets: Number.isFinite(baseRule.maxAssets) && baseRule.maxAssets > 0
+      ? baseRule.maxAssets
+      : fallback.maxAssets,
+  };
+}
+
+function normalizeRegistryKind(group, item) {
+  if (item.kind) return item.kind;
+  if (REGISTRY_GROUP_KIND[group]) return REGISTRY_GROUP_KIND[group];
+  return group.replace(/s$/, '');
+}
+
+function flattenRegistryAssets(registryIndex = {}) {
+  const groups = registryIndex.assets || {};
+  const result = [];
+  for (const [group, items] of Object.entries(groups)) {
+    if (!Array.isArray(items)) continue;
+    for (const item of items) {
+      result.push({
+        ...item,
+        kind: normalizeRegistryKind(group, item),
+      });
+    }
+  }
+  return result;
+}
+
+function matchesStageLoadWhen(asset, stage) {
+  const loadWhen = asset.loadWhen;
+  if (!loadWhen) return true;
+  if (Array.isArray(loadWhen.exceptStages) && loadWhen.exceptStages.includes(stage)) return false;
+  if (Array.isArray(loadWhen.stages)) return loadWhen.stages.includes(stage);
+  if (loadWhen.stage) return loadWhen.stage === stage;
+  return true;
+}
+
+function identity(asset) {
+  return `${asset.kind || ''}:${asset.slug || ''}:${asset.version || ''}`;
+}
+
+class ContextPlanner {
+  plan(input = {}) {
+    const stage = input.stage;
+    assertValidStage(stage);
+
+    const stageLoadRule = resolveStageRule(stage, input.contextIndex || {});
+    const registryAssets = flattenRegistryAssets(input.registryIndex || {});
+    const warnings = [];
+    const reasons = [
+      `阶段 ${stage} 使用 loadKinds=${stageLoadRule.loadKinds.join(', ')}，maxAssets=${stageLoadRule.maxAssets}`,
+    ];
+
+    const selected = [];
+    const selectedIds = new Set();
+
+    for (const agentSlug of stageLoadRule.requiredAgents) {
+      const agent = registryAssets.find((asset) => asset.kind === 'agent-profile' && asset.slug === agentSlug);
+      if (!agent) {
+        warnings.push(createIssue(
+          'warning',
+          'CONTEXT_REQUIRED_AGENT_MISSING',
+          `阶段 ${stage} 缺少必需 Agent Profile：${agentSlug}`,
+          '请执行 ai-spec-auto sync . 或检查 registry.index.json',
+        ));
+        continue;
+      }
+      selected.push({
+        ...agent,
+        required: true,
+        requiredReason: `阶段 ${stage} 要求加载 Agent Profile ${agentSlug}`,
+      });
+      selectedIds.add(identity(agent));
+      reasons.push(`加载 ${agentSlug}：阶段要求的 requiredAgents`);
+    }
+
+    for (const asset of registryAssets) {
+      if (selected.length >= stageLoadRule.maxAssets) break;
+      if (!stageLoadRule.loadKinds.includes(asset.kind)) continue;
+      if (!matchesStageLoadWhen(asset, stage)) continue;
+      if (selectedIds.has(identity(asset))) continue;
+      selected.push({
+        ...asset,
+        required: asset.required === true,
+        requiredReason: `kind=${asset.kind} 匹配 ${stage} 阶段加载规则`,
+      });
+      selectedIds.add(identity(asset));
+      reasons.push(`加载 ${asset.slug || asset.checksum}：kind=${asset.kind} 匹配阶段规则`);
+    }
+
+    if (selected.length === 0) {
+      warnings.push(createIssue(
+        'warning',
+        'CONTEXT_ASSET_NOT_MATCHED',
+        `阶段 ${stage} 没有匹配资产`,
+        '如需加载上下文，请先执行 sync 并确认 registry.index.json 中包含对应 kind',
+      ));
+    }
+
+    return {
+      stage,
+      loadKinds: stageLoadRule.loadKinds,
+      requiredAgents: stageLoadRule.requiredAgents,
+      maxAssets: stageLoadRule.maxAssets,
+      assetsToLoad: selected.slice(0, stageLoadRule.maxAssets),
+      overlaysToLoad: [],
+      sharedContractsToLoad: [],
+      reasons,
+      warnings,
+      stageLoadRule,
+    };
+  }
+}
+
+module.exports = {
+  ContextPlanner,
+  flattenRegistryAssets,
+  resolveStageRule,
+};

package/src/context/types.js

@@ -0,0 +1,96 @@
+const CONTEXT_SCHEMA_VERSION = '1.0.0';
+
+const CONTEXT_STAGES = [
+  'planning',
+  'implementation',
+  'verification',
+  'review',
+  'diagnosing',
+  'recovering',
+];
+
+const DEFAULT_TOKEN_BUDGET = {
+  maxInputTokens: 80000,
+  warningThreshold: 60000,
+};
+
+const DEFAULT_STAGE_LOAD_RULES = [
+  {
+    stage: 'planning',
+    loadKinds: ['role', 'flow'],
+    maxAssets: 5,
+  },
+  {
+    stage: 'implementation',
+    loadKinds: ['rule', 'skill', 'agent-profile'],
+    maxAssets: 8,
+  },
+  {
+    stage: 'verification',
+    loadKinds: ['rule', 'flow'],
+    maxAssets: 6,
+  },
+  {
+    stage: 'review',
+    loadKinds: ['rule'],
+    maxAssets: 6,
+  },
+  {
+    stage: 'diagnosing',
+    loadKinds: ['rule', 'skill', 'agent-profile'],
+    requiredAgents: ['diagnostic-agent'],
+    maxAssets: 6,
+  },
+  {
+    stage: 'recovering',
+    loadKinds: ['rule', 'skill', 'agent-profile'],
+    maxAssets: 6,
+  },
+];
+
+const CONTEXT_PRIVACY_FLAGS = {
+  sourceCodeIncluded: false,
+  rawPromptIncluded: false,
+  rawResponseIncluded: false,
+  absolutePathIncluded: false,
+};
+
+function normalizeTokenBudget(tokenBudget = {}) {
+  return {
+    maxInputTokens: Number.isFinite(tokenBudget.maxInputTokens)
+      ? tokenBudget.maxInputTokens
+      : DEFAULT_TOKEN_BUDGET.maxInputTokens,
+    warningThreshold: Number.isFinite(tokenBudget.warningThreshold)
+      ? tokenBudget.warningThreshold
+      : DEFAULT_TOKEN_BUDGET.warningThreshold,
+  };
+}
+
+function normalizeContextOptions(options = {}) {
+  return {
+    explain: Boolean(options.explain),
+    allowMissingOptionalAssets: options.allowMissingOptionalAssets !== false,
+  };
+}
+
+function assertValidStage(stage) {
+  if (!CONTEXT_STAGES.includes(stage)) {
+    throw new Error(`非法 Context stage：${stage || '未提供'}，允许值：${CONTEXT_STAGES.join(', ')}`);
+  }
+}
+
+function createIssue(level, code, message, suggestion) {
+  return { level, code, message, suggestion };
+}
+
+module.exports = {
+  CONTEXT_PRIVACY_FLAGS,
+  CONTEXT_SCHEMA_VERSION,
+  CONTEXT_STAGES,
+  DEFAULT_STAGE_LOAD_RULES,
+  DEFAULT_TOKEN_BUDGET,
+  assertValidStage,
+  createIssue,
+  normalizeContextOptions,
+  normalizeTokenBudget,
+};

package/src/contracts/index.js

@@ -0,0 +1,63 @@
+const fs = require('fs');
+const path = require('path');
+
+const CONTRACT_ROOT = path.join(__dirname, '..', '..', 'contracts');
+
+const CONTRACTS = {
+  runEvent: {
+    schema: 'run-event.schema.json',
+    fixture: 'run-event.fixture.json',
+  },
+  evidenceReport: {
+    schema: 'evidence-report.schema.json',
+    fixture: 'evidence-report.fixture.json',
+  },
+  assetPackage: {
+    schema: 'asset-package.schema.json',
+    fixture: 'asset-package.fixture.json',
+  },
+  manifest: {
+    schema: 'manifest.schema.json',
+    fixture: 'manifest.fixture.json',
+  },
+  assetUsageFeedback: {
+    schema: 'asset-usage-feedback.schema.json',
+    fixture: 'asset-usage-feedback.fixture.json',
+  },
+};
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function resolveContractPath(kind, type) {
+  const contract = CONTRACTS[kind];
+  if (!contract) throw new Error(`未知协议：${kind}`);
+  const dir = type === 'schema' ? 'schemas' : 'fixtures';
+  return path.join(CONTRACT_ROOT, dir, contract[type]);
+}
+
+function loadSchema(kind) {
+  return readJson(resolveContractPath(kind, 'schema'));
+}
+
+function loadFixture(kind) {
+  return readJson(resolveContractPath(kind, 'fixture'));
+}
+
+function listContracts() {
+  return Object.keys(CONTRACTS).map((kind) => ({
+    kind,
+    schemaPath: resolveContractPath(kind, 'schema'),
+    fixturePath: resolveContractPath(kind, 'fixture'),
+  }));
+}
+
+module.exports = {
+  CONTRACT_ROOT,
+  CONTRACTS,
+  listContracts,
+  loadFixture,
+  loadSchema,
+  resolveContractPath,
+};

package/src/executor/executor-registry.js

@@ -0,0 +1,78 @@
+const { CodexExecutorProvider } = require('./providers/codex-executor-provider');
+const { CursorExecutorProvider } = require('./providers/cursor-executor-provider');
+const { ClaudeCodeExecutorProvider } = require('./providers/claude-code-executor-provider');
+
+class ExecutorRegistry {
+  constructor(options = {}) {
+    this.providers = new Map();
+    const providers = Object.prototype.hasOwnProperty.call(options, 'providers')
+      ? options.providers
+      : [
+        new CodexExecutorProvider(),
+        new CursorExecutorProvider(),
+        new ClaudeCodeExecutorProvider(),
+      ];
+    for (const provider of providers || []) {
+      this.register(provider);
+    }
+  }
+
+  register(provider) {
+    if (!provider || !provider.name) {
+      throw new Error('执行器注册失败：Provider 缺少 name。');
+    }
+    this.providers.set(provider.name, provider);
+    return provider;
+  }
+
+  get(name) {
+    return this.providers.get(name) || null;
+  }
+
+  has(name) {
+    return this.providers.has(name);
+  }
+
+  list() {
+    return Array.from(this.providers.values()).map((provider) => ({
+      name: provider.name,
+      displayName: provider.displayName,
+      capabilities: provider.capabilities || [],
+      provider,
+    }));
+  }
+
+  async getAvailableProviders(input = {}) {
+    const available = [];
+    const unavailable = [];
+    for (const provider of this.providers.values()) {
+      try {
+        const availability = await provider.checkAvailability(input);
+        if (availability.available) {
+          available.push({ provider, availability });
+        } else {
+          unavailable.push({
+            name: provider.name,
+            displayName: provider.displayName,
+            reason: availability.reason || '执行器不可用。',
+            fixSuggestion: availability.fixSuggestion || null,
+            version: availability.version || null,
+          });
+        }
+      } catch (error) {
+        unavailable.push({
+          name: provider.name,
+          displayName: provider.displayName,
+          reason: `执行器可用性检查失败：${error.message}`,
+          fixSuggestion: '请检查执行器安装状态，或切换其他执行器。',
+          version: null,
+        });
+      }
+    }
+    return { available, unavailable };
+  }
+}
+
+module.exports = {
+  ExecutorRegistry,
+};

package/src/executor/executor-result-parser.js

@@ -0,0 +1,44 @@
+const { ExecutorStatus, createExecutionResult, createExecutorErrorResult } = require('./types');
+
+const VALID_STATUSES = new Set(Object.values(ExecutorStatus));
+
+function isRelativePath(value) {
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('/') && !/^[A-Za-z]:[\\/]/.test(value);
+}
+
+function normalizeChangedFiles(changedFiles) {
+  if (!Array.isArray(changedFiles)) return [];
+  return changedFiles
+    .map((item) => (typeof item === 'string' ? { path: item } : item))
+    .filter((item) => item && isRelativePath(item.path))
+    .map((item) => ({
+      path: item.path,
+      status: item.status || 'modified',
+    }));
+}
+
+function normalizeExecutionResult(raw) {
+  if (!raw || typeof raw !== 'object' || typeof raw.success !== 'boolean' || !VALID_STATUSES.has(raw.status)) {
+    return createExecutorErrorResult(
+      'EXECUTOR_RESULT_INVALID',
+      '执行器返回结果不符合 ExecutorExecutionResult 契约。',
+      '请检查 Provider 实现，确保返回 success、status、summary、changedFiles、verification、tokenUsage、riskList、error。'
+    );
+  }
+
+  return createExecutionResult({
+    success: raw.success,
+    status: raw.status,
+    summary: raw.summary || '',
+    changedFiles: normalizeChangedFiles(raw.changedFiles),
+    verification: raw.verification || {},
+    tokenUsage: raw.tokenUsage || {},
+    riskList: Array.isArray(raw.riskList) ? raw.riskList : [],
+    error: raw.error || null,
+  });
+}
+
+module.exports = {
+  normalizeChangedFiles,
+  normalizeExecutionResult,
+};

package/src/executor/executor-runner.js

@@ -0,0 +1,141 @@
+const { ExecutorRegistry } = require('./executor-registry');
+const { normalizeExecutionResult } = require('./executor-result-parser');
+const { ExecutorSelector } = require('./executor-selector');
+const { withExecutorTimeout } = require('./executor-timeout');
+const {
+  DEFAULT_EXECUTOR_TIMEOUT_MS,
+  ExecutorStatus,
+  createExecutorErrorResult,
+} = require('./types');
+
+class ExecutorRunner {
+  constructor(options = {}) {
+    this.registry = options.registry || new ExecutorRegistry();
+    this.selector = options.selector || new ExecutorSelector();
+  }
+
+  async run(input = {}) {
+    let selection;
+    let prepareResult = null;
+    try {
+      selection = await this.selector.select({
+        cliExecutor: input.cliExecutor || null,
+        agentProfile: input.agentProfile || null,
+        policy: input.policy || null,
+        mode: input.mode || 'local-assisted',
+        registry: input.registry || this.registry,
+        projectRoot: input.projectRoot,
+        worktreePath: input.worktreePath || null,
+        env: input.env || process.env,
+        dryRun: input.dryRun === true,
+      });
+    } catch (error) {
+      const result = createExecutorErrorResult(
+        error.code || 'EXECUTOR_SELECT_FAILED',
+        error.message,
+        error.suggestion || '请执行 ai-spec-auto executor check 查看可用执行器。'
+      );
+      result.selection = null;
+      result.prepare = null;
+      persistExecutorResult(input, result);
+      return result;
+    }
+
+    try {
+      if (input.dryRun !== true) {
+        const availability = await selection.provider.checkAvailability({
+          projectRoot: input.projectRoot,
+          worktreePath: input.worktreePath || null,
+          env: input.env || process.env,
+        });
+        if (!availability.available) {
+          const result = createExecutorErrorResult(
+            'EXECUTOR_NOT_AVAILABLE',
+            availability.reason || '执行器不可用。',
+            availability.fixSuggestion || '请切换执行器后重试。'
+          );
+          result.selection = selection;
+          result.prepare = null;
+          return result;
+        }
+      }
+
+      prepareResult = await selection.provider.prepare({
+        run: input.run,
+        contextBundle: input.contextBundle,
+        projectRoot: input.projectRoot,
+        worktreePath: input.worktreePath || null,
+        requirement: input.requirement,
+        stage: input.stage || 'implementation',
+      });
+      if (!prepareResult || prepareResult.prepared !== true || (prepareResult.errors || []).length > 0) {
+        const message = prepareResult && prepareResult.errors && prepareResult.errors[0]
+          ? prepareResult.errors[0].message
+          : '执行器 prepare 阶段失败。';
+        const result = createExecutorErrorResult('EXECUTOR_PREPARE_FAILED', message, '请检查执行器任务文件写入权限和项目初始化状态。');
+        result.selection = selection;
+        result.prepare = prepareResult;
+        return result;
+      }
+
+      const rawResult = await withExecutorTimeout(() => selection.provider.execute({
+        run: input.run,
+        projectRoot: input.projectRoot,
+        worktreePath: input.worktreePath || null,
+        instructionFilePath: prepareResult.instructionFilePath,
+        executorInputPath: prepareResult.executorInputPath,
+        timeoutMs: input.timeoutMs || DEFAULT_EXECUTOR_TIMEOUT_MS,
+        dryRun: input.dryRun === true,
+        env: input.env || process.env,
+      }), input.timeoutMs || DEFAULT_EXECUTOR_TIMEOUT_MS);
+
+      const result = normalizeExecutionResult(rawResult);
+      result.selection = selection;
+      result.prepare = prepareResult;
+      persistExecutorResult(input, result);
+      return result;
+    } catch (error) {
+      const isTimeout = error.code === 'EXECUTOR_TIMEOUT';
+      const result = createExecutorErrorResult(
+        error.code || 'EXECUTOR_RUN_FAILED',
+        error.message || '执行器执行失败。',
+        error.suggestion || '请查看 run.json 事件和执行器输出摘要。',
+        isTimeout ? ExecutorStatus.TIMEOUT : ExecutorStatus.FAILED
+      );
+      result.selection = selection;
+      result.prepare = prepareResult;
+      persistExecutorResult(input, result);
+      return result;
+    }
+  }
+}
+
+function persistExecutorResult(input, result) {
+  if (!input.runService || !input.run || !input.run.runId || !input.projectRoot) return;
+  input.runService.updateExecutor(input.projectRoot, input.run.runId, {
+    type: result.selection ? result.selection.executor : null,
+    status: result.status,
+    selectionReason: result.selection ? result.selection.reason : '',
+    fallbackTried: result.selection ? result.selection.fallbackTried : [],
+    warnings: [
+      ...((result.selection && result.selection.warnings) || []),
+      ...((result.prepare && result.prepare.warnings) || []),
+    ],
+    prepared: result.prepare ? {
+      executorInputPath: result.prepare.executorInputPath,
+      instructionFilePath: result.prepare.instructionFilePath,
+    } : null,
+    lastResult: {
+      success: result.success,
+      status: result.status,
+      summary: result.summary,
+      error: result.error,
+      changedFiles: result.changedFiles || [],
+      tokenUsage: result.tokenUsage || null,
+    },
+  });
+}
+
+module.exports = {
+  ExecutorRunner,
+};