@jsonstudio/rcc 0.89.3 → 0.89.164

package/scripts/tests/apply-patch-loop.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { TextDecoder } from 'node:util';
 import { Readable } from 'node:stream';
@@ -14,6 +15,11 @@ const PROJECT_ROOT = path.resolve(__dirname, '../..');
 const MOCK_SAMPLES_DIR = path.join(PROJECT_ROOT, 'samples/mock-provider');
 const PORT = Number(process.env.RCC_TOOL_LOOP_PORT || 5555);
 const BASE_URL = `http://127.0.0.1:${PORT}`;
+const HOME = os.homedir();
+const STAGE_DIR = path.join(HOME, '.routecodex', 'golden_samples', 'openai-responses');
+const STAGE_SUFFIX = '_req_outbound_stage2_format_build.json';
+const STAGE1_SUFFIX = '_req_outbound_stage1_semantic_map.json';
+const MOCK_PROVIDER_ID = 'mock.apply_patch.toolloop';
 
 function listProcessesOnPort(port) {
   try {
@@ -59,6 +65,84 @@ async function ensurePortFree(port) {
   await delay(200);
 }
 
+async function snapshotStageFiles() {
+  try {
+    const entries = await fs.readdir(STAGE_DIR);
+    return new Set(entries.filter((name) => name.endsWith(STAGE_SUFFIX)));
+  } catch {
+    return new Set();
+  }
+}
+
+async function diffStageFiles(beforeSet) {
+  try {
+    const entries = await fs.readdir(STAGE_DIR);
+    return entries
+      .filter((name) => name.endsWith(STAGE_SUFFIX))
+      .filter((name) => !beforeSet.has(name));
+  } catch {
+    return [];
+  }
+}
+
+async function waitForMockStage(beforeSet, timeoutMs = 10000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const candidates = await diffStageFiles(beforeSet);
+    for (const name of candidates) {
+      const stage1Name = name.replace(STAGE_SUFFIX, STAGE1_SUFFIX);
+      const stage1Path = path.join(STAGE_DIR, stage1Name);
+      try {
+        await fs.access(stage1Path);
+      } catch {
+        continue;
+      }
+      let providerId = '';
+      try {
+        const stage1Doc = JSON.parse(await fs.readFile(stage1Path, 'utf-8'));
+        providerId = stage1Doc?.body?.meta?.context?.providerId ?? '';
+      } catch {
+        providerId = '';
+      }
+      if (typeof providerId === 'string' && providerId === MOCK_PROVIDER_ID) {
+        return path.join(STAGE_DIR, name);
+      }
+    }
+    await delay(250);
+  }
+  throw new Error('mock apply_patch stage snapshot not found (enable ROUTECODEX_STAGE_LOG)');
+}
+
+async function verifyApplyPatchTool(stagePath) {
+  const raw = await fs.readFile(stagePath, 'utf-8');
+  const doc = JSON.parse(raw);
+  const payload = doc?.body ?? doc;
+  const tools = Array.isArray(payload?.tools) ? payload.tools : [];
+  if (!tools.length) {
+    throw new Error('provider payload missing tools array');
+  }
+  const match = tools.find((tool) => {
+    const name = tool?.name || tool?.function?.name;
+    return typeof name === 'string' && name.trim() === 'apply_patch';
+  });
+  if (!match) {
+    throw new Error('apply_patch tool declaration missing in provider payload');
+  }
+  const params = match.parameters || match.function?.parameters;
+  const props = params?.properties;
+  const inputField = props?.input;
+  if (!inputField || typeof inputField !== 'object') {
+    throw new Error('apply_patch.parameters.input missing');
+  }
+  if (String(inputField.type).toLowerCase() !== 'string') {
+    throw new Error('apply_patch.parameters.input must be a string');
+  }
+  const required = Array.isArray(params?.required) ? params.required.map((v) => String(v)) : [];
+  if (!required.includes('input')) {
+    throw new Error('apply_patch.parameters.required must include \"input\"');
+  }
+}
+
 function buildMockConfig(port) {
   return {
     version: '1.0.0',
@@ -210,11 +294,12 @@ async function requestApplyPatchLoop() {
       responseId = String(data?.response?.id || '');
       console.log(`[tool-loop] response.created id=${responseId}`);
     } else if (ev.event === 'response.required_action') {
-      toolCalls = Array.isArray(data?.required_action?.submit_tool_outputs?.tool_calls)
-        ? data.required_action.submit_tool_outputs.tool_calls
-        : [];
-      console.log(`[tool-loop] required_action tool_calls=${toolCalls.length}`);
-      break;
+      if (!toolCalls.length) {
+        toolCalls = Array.isArray(data?.required_action?.submit_tool_outputs?.tool_calls)
+          ? data.required_action.submit_tool_outputs.tool_calls
+          : [];
+        console.log(`[tool-loop] required_action tool_calls=${toolCalls.length}`);
+      }
     }
   }
 
@@ -231,7 +316,8 @@ async function requestApplyPatchLoop() {
   let patchText = '';
   try {
     const parsed = JSON.parse(firstCall.function.arguments || '{}');
-    patchText = String(parsed?.patch || '');
+    const diffText = parsed?.input ?? parsed?.patch;
+    patchText = typeof diffText === 'string' ? diffText : '';
   } catch {
     throw new Error('apply_patch.arguments JSON parse failed');
   }
@@ -264,12 +350,12 @@ function buildResponsesPayload() {
         parameters: {
           type: 'object',
           properties: {
-            patch: {
+            input: {
               type: 'string',
               description: 'Unified diff patch content (*** Begin Patch ... *** End Patch)'
             }
           },
-          required: ['patch'],
+          required: ['input'],
           additionalProperties: false
         },
         strict: true
@@ -336,13 +422,18 @@ async function main() {
       ROUTECODEX_MOCK_CONFIG_PATH: file,
       ROUTECODEX_MOCK_SAMPLES_DIR: MOCK_SAMPLES_DIR,
       ROUTECODEX_MOCK_VALIDATE_NAMES: '1',
+      ROUTECODEX_CONFIG_PATH: file,
       ROUTECODEX_PORT: String(PORT),
-      ROUTECODEX_STAGE_LOG: process.env.ROUTECODEX_STAGE_LOG ?? '0'
+      ROUTECODEX_STAGE_LOG: '1'
     }
   });
   try {
     await waitForHealth(server);
+    const stageBefore = await snapshotStageFiles();
     const { responseId, toolCalls, patchText } = await requestApplyPatchLoop();
+    const stagePath = await waitForMockStage(stageBefore);
+    await verifyApplyPatchTool(stagePath);
+    console.log(`[tool-loop] verified provider payload stage → ${stagePath}`);
     await submitToolOutputs(responseId, toolCalls, patchText);
     console.log('[tool-loop] apply_patch loop PASSED');
   } finally {

package/scripts/tests/golden-provider-cycle.mjs

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 
+import fs from 'node:fs';
+import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
+const HOME = os.homedir();
+const USER_SAMPLES_HINT = path.join(HOME, '.routecodex', 'codex-samples');
 
 function run(command, args, env = {}) {
   return new Promise((resolve, reject) => {
@@ -27,7 +31,14 @@ async function main() {
     '--custom-only',
     '--update-golden'
   ]);
-  await run('node', ['scripts/mock-provider/run-regressions.mjs']);
+  await run('node', ['scripts/mock-provider/run-regressions.mjs'], {
+    ROUTECODEX_MOCK_ENTRY_FILTER: 'all'
+  });
+  if (fs.existsSync(USER_SAMPLES_HINT)) {
+    console.log('[golden-cycle] detected ~/.routecodex/codex-samples; run "node scripts/mock-provider/capture-from-configs.mjs" to ingest latest provider recordings for deep regression.');
+  } else {
+    console.log('[golden-cycle] ~/.routecodex/codex-samples missing; skipping deep regression (optional).');
+  }
 }
 
 main().catch((error) => {

package/scripts/tests/responses-provider-dry-run.mjs

@@ -32,6 +32,20 @@ if (!providerDef) usage(`Provider "${providerId}" not found in config`);
 const auth = providerDef.auth || {};
 const apiKey = auth.apiKey || auth.value || process.env.DRY_RUN_API_KEY || 'dry-run-key';
 
+const legacyCompatFields = [];
+if (typeof providerDef.compatibility_profile === 'string') legacyCompatFields.push('compatibility_profile');
+if (typeof providerDef.compat === 'string') legacyCompatFields.push('compat');
+if (providerDef.compatibility && typeof providerDef.compatibility === 'object') {
+  if (typeof providerDef.compatibility.profile === 'string') legacyCompatFields.push('compatibility.profile');
+  if (typeof providerDef.compatibility.id === 'string') legacyCompatFields.push('compatibility.id');
+}
+if (legacyCompatFields.length > 0) {
+  usage(`Provider "${providerId}" uses legacy compatibility field(s): ${legacyCompatFields.join(', ')}. Rename to "compatibilityProfile".`);
+}
+const compatProfile =
+  (typeof providerDef.compatibilityProfile === 'string' && providerDef.compatibilityProfile.trim()) ||
+  undefined;
+
 const runtime = {
   runtimeKey: `${providerId}.dry`,
   providerId,
@@ -42,7 +56,7 @@ const runtime = {
     type: 'apikey',
     value: apiKey
   },
-  compatibilityProfile: providerDef.compat || 'default',
+  compatibilityProfile: compatProfile,
   outboundProfile: providerDef.type === 'responses' ? 'openai-responses' : 'openai-chat',
   defaultModel: modelId
 };

package/scripts/tests/virtual-router-health.mjs

@@ -45,7 +45,7 @@ function buildProviderProfile(providerKey, endpoint) {
     endpoint,
     auth: { type: 'apiKey', secretRef: providerKey },
     outboundProfile: 'openai-chat',
-    compatibilityProfile: 'default',
+    compatibilityProfile: 'compat:passthrough',
     defaultModel: 'sim-model'
   };
 }
@@ -65,7 +65,7 @@ function createRouterConfig() {
     routing,
     providers,
     classifier: {
-      longContextThresholdTokens: 60000,
+      longContextThresholdTokens: 180000,
       thinkingKeywords: ['think', '考', 'reason'],
       backgroundKeywords: []
     },
@@ -128,9 +128,9 @@ class VirtualRouterSimulator {
     return event;
   }
 
-  runRoute(label = 'default') {
+  runRoute(label = 'default', text) {
     const requestId = `req_${++this.sequence}`;
-    const request = cloneRequest(`scenario:${label}:${Date.now()}`);
+    const request = cloneRequest(text ?? `scenario:${label}:${Date.now()}`);
     const metadata = {
       requestId,
       entryEndpoint: '/v1/chat/completions',
@@ -227,6 +227,12 @@ async function scenarioScheduler(sim) {
   sim.runRoute('thinking');
 }
 
+async function scenarioRoutingDirectives(sim) {
+  sim.runRoute('baseline', '普通请求');
+  sim.runRoute('forced-thinking', '请仔细分析这个问题 <**thinking**>');
+  sim.runRoute('forced-provider', '请强制使用这个provider <**charlie.sim-model**> 来回答');
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
@@ -240,7 +246,8 @@ async function main() {
     ['client-error', scenarioClientError],
     ['upstream', scenarioUpstream],
     ['timeout', scenarioTimeout],
-    ['scheduler', scenarioScheduler]
+    ['scheduler', scenarioScheduler],
+    ['routing-directives', scenarioRoutingDirectives]
   ];
 
   const summary = [];

package/scripts/tools/capture-provider-goldens.mjs

@@ -15,7 +15,11 @@ const HOME = os.homedir();
 const PROVIDER_ROOT = path.join(HOME, '.routecodex', 'provider');
 const SNAPSHOT_ROOT = path.join(HOME, '.routecodex', 'golden_samples');
 const PROVIDER_GOLDEN_ROOT = path.join(SNAPSHOT_ROOT, 'provider_golden_samples');
-const CUSTOM_SAMPLE_ROOT = path.join(SNAPSHOT_ROOT, 'new');
+const CI_GOLDENS_ROOT = path.join(ROOT, 'samples', 'ci-goldens');
+const CUSTOM_SAMPLE_ROOTS = [
+  path.join(SNAPSHOT_ROOT, 'new'),
+  CI_GOLDENS_ROOT
+];
 const TEMP_ROOT = path.join(process.cwd(), 'tmp', 'provider-captures');
 const STAGE_DIRS = {
   'openai-chat': path.join(SNAPSHOT_ROOT, 'openai-chat'),
@@ -138,7 +142,7 @@ function ensureDir(p) {
 function listProviderConfigs() {
   const entries = [];
   if (!fs.existsSync(PROVIDER_ROOT)) {
-    throw new Error(`Provider directory missing: ${PROVIDER_ROOT}`);
+    return entries;
   }
   for (const dir of fs.readdirSync(PROVIDER_ROOT)) {
     const absDir = path.join(PROVIDER_ROOT, dir);
@@ -169,6 +173,39 @@ function listProviderConfigs() {
   return entries;
 }
 
+function mapEntryTypeToProviderType(entryType) {
+  if (entryType === 'anthropic-messages') return 'anthropic-http-provider';
+  if (entryType === 'openai-responses') return 'responses-http-provider';
+  return 'openai-http-provider';
+}
+
+function listCiGoldenProviders() {
+  const entries = [];
+  if (!fs.existsSync(CI_GOLDENS_ROOT)) {
+    return entries;
+  }
+  for (const entryType of fs.readdirSync(CI_GOLDENS_ROOT)) {
+    const entryDir = path.join(CI_GOLDENS_ROOT, entryType);
+    if (!fs.statSync(entryDir).isDirectory()) continue;
+    for (const providerId of fs.readdirSync(entryDir)) {
+      const providerDir = path.join(entryDir, providerId);
+      if (!fs.statSync(providerDir).isDirectory()) continue;
+      entries.push({
+        dir: 'ci-goldens',
+        configFile: path.join(providerDir, 'request.sample.json'),
+        providerId,
+        providerConfig: {
+          id: providerId,
+          type: mapEntryTypeToProviderType(entryType)
+        },
+        doc: null,
+        entryTypeOverride: entryType
+      });
+    }
+  }
+  return entries;
+}
+
 function detectEntryType(providerConfig) {
   const type = String(providerConfig?.type || '').toLowerCase();
   if (type.includes('anthropic')) return 'anthropic-messages';
@@ -309,24 +346,30 @@ function diffJson(expected, actual, prefix = '<root>') {
 }
 
 function loadCustomSample(providerId, entryType) {
-  const dir = path.join(CUSTOM_SAMPLE_ROOT, entryType, providerId);
-  const samplePath = path.join(dir, 'request.sample.json');
-  if (!fs.existsSync(samplePath)) return null;
-  let stageFile;
-  const metaPath = path.join(dir, 'meta.json');
-  if (fs.existsSync(metaPath)) {
-    try {
-      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-      stageFile = meta?.stageFile;
-    } catch (error) {
-      console.warn(`[capture] custom meta parse failed for ${providerId}/${entryType}: ${error.message}`);
+  for (const root of CUSTOM_SAMPLE_ROOTS) {
+    if (!root) continue;
+    const dir = path.join(root, entryType, providerId);
+    const samplePath = path.join(dir, 'request.sample.json');
+    if (!fs.existsSync(samplePath)) {
+      continue;
     }
+    let stageFile;
+    const metaPath = path.join(dir, 'meta.json');
+    if (fs.existsSync(metaPath)) {
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        stageFile = meta?.stageFile || meta?.originStage || null;
+      } catch (error) {
+        console.warn(`[capture] custom meta parse failed for ${providerId}/${entryType}: ${error.message}`);
+      }
+    }
+    return {
+      body: JSON.parse(fs.readFileSync(samplePath, 'utf-8')),
+      stageFile,
+      dir
+    };
   }
-  return {
-    body: JSON.parse(fs.readFileSync(samplePath, 'utf-8')),
-    stageFile,
-    dir
-  };
+  return null;
 }
 
 function saveProviderSample(providerId, entryType, sourceStagePath, providedBody, updateGolden) {
@@ -427,24 +470,26 @@ async function captureProvider(providerEntry, entryType, port, options, sanitize
 async function main() {
   const options = parseArgs();
   ensureDir(TEMP_ROOT);
-  const providers = listProviderConfigs();
+  const providers = [
+    ...listProviderConfigs(),
+    ...listCiGoldenProviders()
+  ];
+  if (!providers.length) {
+    console.warn('[capture] no provider configs or ci goldens detected; exiting');
+    return;
+  }
   const captured = new Set();
   const results = [];
   let portBase = 5800;
 
   for (const entry of providers) {
-    const entryType = detectEntryType(entry.providerConfig);
+    const entryType = entry.entryTypeOverride || detectEntryType(entry.providerConfig);
     const entryDef = ENTRY_DEFS[entryType];
     if (!entryDef) continue;
     const captureKey = `${entry.providerId}:${entryType}`;
     if (captured.has(captureKey)) {
       continue;
     }
-    const sampleExists = fs.existsSync(entryDef.samplePath);
-    if (!sampleExists) {
-      results.push({ provider: entry.providerId, entryType, status: 'skipped', reason: 'sample missing' });
-      continue;
-    }
     const custom = loadCustomSample(entry.providerId, entryType);
     if (custom) {
       console.log(`[capture] using custom sample for ${entry.providerId} (${entryType}) from ${custom.dir}`);
@@ -459,6 +504,11 @@ async function main() {
       });
       continue;
     }
+    const sampleExists = fs.existsSync(entryDef.samplePath);
+    if (!sampleExists) {
+      results.push({ provider: entry.providerId, entryType, status: 'skipped', reason: 'sample missing' });
+      continue;
+    }
     if (options.customOnly) {
       results.push({
         provider: entry.providerId,

package/scripts/tools/responses-golden-dry-run.mjs

@@ -64,6 +64,22 @@ function resolveProviderRuntime(configPath, target) {
   const auth = providerDef.auth || {};
   const apiKey = auth.apiKey || auth.value || process.env.C4M_API_KEY || process.env.RCC_PROVIDER_KEY;
   if (!apiKey) throw new Error(`Missing API key for ${providerId} (set in config or env)`);
+const legacyCompatFields = [];
+if (typeof providerDef.compatibility_profile === 'string') legacyCompatFields.push('compatibility_profile');
+if (typeof providerDef.compat === 'string') legacyCompatFields.push('compat');
+if (providerDef.compatibility && typeof providerDef.compatibility === 'object') {
+  if (typeof providerDef.compatibility.profile === 'string') legacyCompatFields.push('compatibility.profile');
+  if (typeof providerDef.compatibility.id === 'string') legacyCompatFields.push('compatibility.id');
+}
+if (legacyCompatFields.length > 0) {
+  throw new Error(
+    `Provider ${providerId} uses legacy compatibility field(s): ${legacyCompatFields.join(
+      ', '
+    )}. Rename to "compatibilityProfile".`
+  );
+}
+const compatProfile =
+  (typeof providerDef.compatibilityProfile === 'string' && providerDef.compatibilityProfile.trim()) || undefined;
   return {
     runtimeKey: `${providerId}.golden.${Date.now()}`,
     providerId,
@@ -72,7 +88,7 @@ function resolveProviderRuntime(configPath, target) {
     providerType: (providerDef.type || 'responses').toLowerCase(),
     endpoint: providerDef.baseURL || providerDef.baseUrl || providerDef.endpoint || 'https://api.example.net/v1',
     auth: { type: 'apikey', value: apiKey },
-    compatibilityProfile: providerDef.compat || 'default',
+    compatibilityProfile: compatProfile,
     outboundProfile: 'openai-responses',
     defaultModel: modelId
   };

package/scripts/tools/responses-provider-replay.mjs

@@ -209,6 +209,22 @@ function resolveProviderRuntime(configPath, target) {
   const auth = providerDef.auth || {};
   const apiKey = auth.apiKey || auth.value || process.env.C4M_API_KEY;
   if (!apiKey) throw new Error(`Missing API key for ${providerId}. set in config or C4M_API_KEY env`);
+  const legacyCompatFields = [];
+  if (typeof providerDef.compatibility_profile === 'string') legacyCompatFields.push('compatibility_profile');
+  if (typeof providerDef.compat === 'string') legacyCompatFields.push('compat');
+  if (providerDef.compatibility && typeof providerDef.compatibility === 'object') {
+    if (typeof providerDef.compatibility.profile === 'string') legacyCompatFields.push('compatibility.profile');
+    if (typeof providerDef.compatibility.id === 'string') legacyCompatFields.push('compatibility.id');
+  }
+  if (legacyCompatFields.length > 0) {
+    throw new Error(
+      `Provider ${providerId} uses legacy compatibility field(s): ${legacyCompatFields.join(
+        ', '
+      )}. Rename to "compatibilityProfile".`
+    );
+  }
+  const compatProfile =
+    (typeof providerDef.compatibilityProfile === 'string' && providerDef.compatibilityProfile.trim()) || undefined;
   return {
     runtime: {
       runtimeKey: `${providerId}.replay.${Date.now()}`,
@@ -218,7 +234,7 @@ function resolveProviderRuntime(configPath, target) {
       providerType: (providerDef.type || 'responses').toLowerCase(),
     endpoint: providerDef.baseURL || providerDef.baseUrl || providerDef.endpoint || 'https://api.example.net/v1',
     auth: { type: 'apikey', value: apiKey },
-    compatibilityProfile: providerDef.compat || 'default',
+    compatibilityProfile: compatProfile,
       outboundProfile: 'openai-responses',
       defaultModel: modelId
     },

package/scripts/tools/sync-ci-goldens.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, '../..');
+const TARGET_ROOT = path.join(PROJECT_ROOT, 'samples', 'ci-goldens');
+const SOURCE_ROOT = path.join(os.homedir(), '.routecodex', 'golden_samples', 'new');
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+
+function writeIfChanged(target, content) {
+  const next = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
+  if (fs.existsSync(target)) {
+    const prev = fs.readFileSync(target, 'utf-8');
+    if (prev === next) {
+      return false;
+    }
+  }
+  fs.writeFileSync(target, next);
+  return true;
+}
+
+function syncProvider(entryType, providerId) {
+  const sourceDir = path.join(SOURCE_ROOT, entryType, providerId);
+  const requestPath = path.join(sourceDir, 'request.sample.json');
+  if (!fs.existsSync(requestPath)) {
+    console.warn(`[sync-ci-goldens] skip ${entryType}/${providerId}: request.sample.json missing`);
+    return { status: 'skipped' };
+  }
+  const targetDir = path.join(TARGET_ROOT, entryType, providerId);
+  ensureDir(targetDir);
+  const targetRequest = path.join(targetDir, 'request.sample.json');
+  const changedRequest = writeIfChanged(targetRequest, fs.readFileSync(requestPath, 'utf-8'));
+  const sourceMetaPath = path.join(sourceDir, 'meta.json');
+  const targetMeta = path.join(targetDir, 'meta.json');
+  if (fs.existsSync(sourceMetaPath)) {
+    const meta = readJson(sourceMetaPath);
+    meta.source = 'ci-goldens';
+    writeIfChanged(targetMeta, meta);
+  } else if (!fs.existsSync(targetMeta)) {
+    const meta = {
+      providerId,
+      entryType,
+      capturedAt: new Date().toISOString(),
+      source: 'ci-goldens',
+      stageFile: null
+    };
+    writeIfChanged(targetMeta, meta);
+  }
+  return { status: changedRequest ? 'updated' : 'unchanged', targetDir };
+}
+
+function listEntries() {
+  if (!fs.existsSync(SOURCE_ROOT)) {
+    throw new Error(`Source golden samples missing: ${SOURCE_ROOT}`);
+  }
+  const entries = [];
+  for (const entryType of fs.readdirSync(SOURCE_ROOT)) {
+    const entryDir = path.join(SOURCE_ROOT, entryType);
+    if (!fs.statSync(entryDir).isDirectory()) continue;
+    for (const providerId of fs.readdirSync(entryDir)) {
+      const providerDir = path.join(entryDir, providerId);
+      if (!fs.statSync(providerDir).isDirectory()) continue;
+      entries.push({ entryType, providerId });
+    }
+  }
+  return entries;
+}
+
+function usage() {
+  console.log('Usage: node scripts/tools/sync-ci-goldens.mjs [--entry <type>] [--provider <id>]');
+  process.exit(0);
+}
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const filters = { entry: null, provider: null };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--entry') {
+      filters.entry = args[++i] || null;
+    } else if (arg === '--provider') {
+      filters.provider = args[++i] || null;
+    } else if (arg === '--help' || arg === '-h') {
+      usage();
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      usage();
+    }
+  }
+  return filters;
+}
+
+function main() {
+  const filters = parseArgs();
+  const entries = listEntries().filter((item) => {
+    if (filters.entry && filters.entry !== item.entryType) return false;
+    if (filters.provider && filters.provider !== item.providerId) return false;
+    return true;
+  });
+  if (!entries.length) {
+    console.warn('[sync-ci-goldens] no matching samples found');
+    return;
+  }
+  let updated = 0;
+  let unchanged = 0;
+  for (const item of entries) {
+    const result = syncProvider(item.entryType, item.providerId);
+    if (result.status === 'updated') updated += 1;
+    else if (result.status === 'unchanged') unchanged += 1;
+  }
+  console.log(`[sync-ci-goldens] synced ${entries.length} provider samples (${updated} updated, ${unchanged} unchanged).`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error('[sync-ci-goldens] failed:', error.message || error);
+  process.exit(1);
+}