@jsonstudio/rcc 0.90.367 → 0.90.701

package/scripts/ensure-llmswitch-mode.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -10,6 +11,33 @@ const rawMode = String(process.env.BUILD_MODE || process.env.RCC_BUILD_MODE || '
 const mode = rawMode === 'dev' ? 'dev' : 'release';
 
 const sharedCoreDir = path.join(PROJECT_ROOT, 'sharedmodule', 'llmswitch-core');
+const nodeModulesScope = path.join(PROJECT_ROOT, 'node_modules', '@jsonstudio');
+const llmsPath = path.join(nodeModulesScope, 'llms');
+
+function runNodeScript(relativePath, args = []) {
+  const scriptPath = path.join(PROJECT_ROOT, relativePath);
+  const res = spawnSync(process.execPath, [scriptPath, ...args], { stdio: 'inherit' });
+  if ((res.status ?? 0) !== 0) {
+    process.exit(res.status ?? 2);
+  }
+}
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function readLink(p) {
+  try {
+    return fs.readlinkSync(p);
+  } catch {
+    return null;
+  }
+}
+
 function exists(p) {
   try {
     fs.accessSync(p);
@@ -22,10 +50,42 @@ function exists(p) {
 function ensureDevLink() {
   if (!exists(sharedCoreDir)) {
     console.error(`[llmswitch:ensure] BUILD_MODE=dev 但未找到 ${sharedCoreDir}`);
-    console.error('[llmswitch:ensure] 现在只支持本地 sharedmodule/llmswitch-core 作为唯一真源。');
+    console.error('[llmswitch:ensure] 请先 clone sharedmodule/llmswitch-core，或改用 BUILD_MODE=release');
     process.exit(2);
   }
-  console.log('[llmswitch:ensure] using local sharedmodule/llmswitch-core');
+  if (isSymlink(llmsPath)) {
+    const target = readLink(llmsPath);
+    if (target) {
+      const resolved = path.resolve(nodeModulesScope, target);
+      const expected = path.resolve(sharedCoreDir);
+      if (resolved === expected) {
+        console.log('[llmswitch:ensure] dev link ok: node_modules/@jsonstudio/llms -> sharedmodule/llmswitch-core');
+        return;
+      }
+    }
+  }
+  console.log('[llmswitch:ensure] linking dev core: node_modules/@jsonstudio/llms -> sharedmodule/llmswitch-core');
+  runNodeScript('scripts/link-llmswitch.mjs');
+}
+
+function ensureReleasePackage() {
+  if (isSymlink(llmsPath)) {
+    console.log('[llmswitch:ensure] release mode: unlinking node_modules/@jsonstudio/llms symlink');
+    runNodeScript('scripts/link-llmswitch.mjs', ['unlink']);
+  }
+  const pkgPath = path.join(llmsPath, 'package.json');
+  if (!exists(pkgPath)) {
+    console.log('[llmswitch:ensure] BUILD_MODE=release: installing @jsonstudio/llms via npm (missing in node_modules)');
+    const res = spawnSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: PROJECT_ROOT, stdio: 'inherit' });
+    if ((res.status ?? 0) !== 0) {
+      process.exit(res.status ?? 2);
+    }
+    if (!exists(pkgPath)) {
+      console.error('[llmswitch:ensure] npm install completed but @jsonstudio/llms is still missing');
+      process.exit(2);
+    }
+  }
+  console.log('[llmswitch:ensure] release package ok: using npm-installed @jsonstudio/llms');
 }
 
 if (exists(sharedCoreDir)) {
@@ -37,7 +97,5 @@ if (exists(sharedCoreDir)) {
 } else if (mode === 'dev') {
   ensureDevLink();
 } else {
-  console.error(`[llmswitch:ensure] BUILD_MODE=release 但未找到 ${sharedCoreDir}`);
-  console.error('[llmswitch:ensure] 当前仓库构建不再支持从 npm 安装 llms core，请恢复本地 sharedmodule/llmswitch-core。');
-  process.exit(2);
+  ensureReleasePackage();
 }

package/scripts/install-global.sh

@@ -45,6 +45,21 @@ check_node() {
     echo "✅ Node.js: $(node -v)"
 }
 
+check_tmux() {
+    if command -v tmux &> /dev/null; then
+        echo "✅ tmux: $(tmux -V 2>/dev/null || echo tmux)"
+        return
+    fi
+
+    echo "❌ tmux 未安装"
+    echo "💡 RouteCodex 的 tmux 会话管理 / 注入 / heartbeat 依赖 tmux"
+    echo "💡 请先安装 tmux 后再执行全局安装，例如："
+    echo "   macOS(Homebrew): brew install tmux"
+    echo "   Ubuntu/Debian: apt-get install -y tmux"
+    echo "   CentOS/RHEL: yum install -y tmux"
+    exit 1
+}
+
 # 构建项目
 build_project() {
     echo "🔨 构建项目..."
@@ -138,12 +153,18 @@ global_install() {
     fi
 }
 
+link_global_llms_dev() {
+    echo "🔗 链接全局 @jsonstudio/llms 到本地 sharedmodule (dev 模式)..."
+    node scripts/link-global-llms-local.mjs --package routecodex --require-target
+}
+
 # 验证安装
 verify_install() {
     echo "🔍 验证全局安装..."
     if command -v routecodex &> /dev/null; then
         echo "✅ routecodex 已全局安装"
         routecodex --version
+        node -e "const path=require('path');const cp=require('child_process');const root=cp.execSync('npm root -g').toString().trim();const pkg=path.join(root,'routecodex','node_modules','@jsonstudio','llms','package.json');const fs=require('fs');if(fs.existsSync(pkg)){const v=require(pkg).version;console.log('🔎 全局 @jsonstudio/llms 版本:',v);}else{console.log('⚠️  未找到全局 @jsonstudio/llms package.json');}"
     else
         echo "❌ 全局安装失败（未找到 routecodex 命令）"
         exit 1
@@ -221,10 +242,12 @@ cleanup_old_install() {
 # 主函数
 main() {
     check_node
+    check_tmux
     cleanup_old_install
     node scripts/cleanup-stale-server-pids.mjs --quiet || true
     build_project
     global_install
+    link_global_llms_dev
     verify_install
     verify_server_health
     restart_managed_dev_server_if_requested

package/scripts/install-release.sh

@@ -14,6 +14,18 @@ fi
 VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "0.0.0")
 echo "📦 当前源码版本: routecodex@${VERSION}"
 
+if command -v tmux >/dev/null 2>&1; then
+  echo "✅ tmux: $(tmux -V 2>/dev/null || echo tmux)"
+else
+  echo "❌ tmux 未安装"
+  echo "💡 RouteCodex/RCC 的 tmux 会话管理 / 注入 / heartbeat 依赖 tmux"
+  echo "💡 请先安装 tmux 后再执行 release 安装，例如："
+  echo "   macOS(Homebrew): brew install tmux"
+  echo "   Ubuntu/Debian: apt-get install -y tmux"
+  echo "   CentOS/RHEL: yum install -y tmux"
+  exit 1
+fi
+
 echo "🔨 构建源码..."
 # release 包：显式使用 BUILD_MODE=release 以便在编译期区分 dev/release
 BUILD_MODE=release npm run build
@@ -25,11 +37,45 @@ if [ "${NEW_VERSION}" != "${VERSION}" ]; then
   VERSION=${NEW_VERSION}
 fi
 
-echo "📦 通过 pack-rcc 生成 @jsonstudio/rcc 发布包..."
-rm -f "jsonstudio-rcc-"*.tgz 2>/dev/null || true
-node scripts/pack-rcc.mjs
+TMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/rcc-release.XXXXXX")
+TARBALL="routecodex-${VERSION}.tgz"
+
+echo "📦 打包当前源码为临时 npm 包..."
+rm -f "routecodex-"*.tgz 2>/dev/null || true
+npm pack --silent
+
+if [ ! -f "${TARBALL}" ]; then
+  echo "❌ 打包失败，未找到 ${TARBALL}"
+  exit 1
+fi
+
+echo "📂 解包到临时目录: ${TMP_DIR}"
+tar xzf "${TARBALL}" -C "${TMP_DIR}"
+PKG_DIR="${TMP_DIR}/package"
 
-RCC_TARBALL="jsonstudio-rcc-${VERSION}.tgz"
+if [ ! -d "${PKG_DIR}" ]; then
+  echo "❌ 解包失败，未找到 ${PKG_DIR}"
+  exit 1
+fi
+
+echo "🛠️  重写临时包为 @jsonstudio/rcc (release)..."
+node - <<'EOF' "${PKG_DIR}"
+const fs = require('fs');
+const path = require('path');
+const pkgDir = process.argv[2];
+const pkgPath = path.join(pkgDir, 'package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+pkg.name = '@jsonstudio/rcc';
+pkg.bin = { rcc: './dist/cli.js' };
+fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+EOF
+
+echo "📦 为 @jsonstudio/rcc (release) 生成独立 tgz 包..."
+(
+  cd "${PKG_DIR}"
+  npm pack --silent
+)
+RCC_TARBALL="${PKG_DIR}/jsonstudio-rcc-${VERSION}.tgz"
 if [ ! -f "${RCC_TARBALL}" ]; then
   echo "❌ 打包 @jsonstudio/rcc 失败，未找到 ${RCC_TARBALL}"
   exit 1
@@ -41,10 +87,14 @@ npm uninstall -g @jsonstudio/rcc >/dev/null 2>&1 || true
 echo "🌍 全局安装 @jsonstudio/rcc (release)..."
 npm install -g "${RCC_TARBALL}" --no-audit --no-fund
 
+echo "🔗 固定全局 rcc 的 @jsonstudio/llms 到本地 sharedmodule/llmswitch-core..."
+node scripts/link-global-llms-local.mjs --package @jsonstudio/rcc --require-target
+
 echo "🔍 验证 rcc 安装..."
 if command -v rcc >/dev/null 2>&1; then
   echo "✅ @jsonstudio/rcc 已全局安装：$(command -v rcc)"
   rcc --version || true
+  node -e "const fs=require('fs');const path=require('path');const cp=require('child_process');const root=cp.execSync('npm root -g').toString().trim();const llmsPath=path.join(root,'@jsonstudio','rcc','node_modules','@jsonstudio','llms');const pkgPath=path.join(llmsPath,'package.json');const link=fs.existsSync(llmsPath)&&fs.lstatSync(llmsPath).isSymbolicLink();const target=link?fs.readlinkSync(llmsPath):'(not-symlink)';const version=fs.existsSync(pkgPath)?JSON.parse(fs.readFileSync(pkgPath,'utf8')).version:'unknown';console.log('🔎 全局 rcc @jsonstudio/llms:',version,'link=',link,'target=',target);"
 else
   echo "❌ 未找到 rcc 命令，请检查 npm 全局安装路径"
   exit 1
@@ -60,7 +110,7 @@ verify_server_request() {
   elif command -v timeout >/dev/null 2>&1; then
     TIMEOUT_BIN="timeout"
   fi
-  local VERIFY_CMD=(node scripts/install-verify.mjs --launcher cli --cli-binary rcc --config "$VERIFY_CONFIG")
+  local VERIFY_CMD=(node scripts/install-verify.mjs --launcher cli --cli-binary rcc --mode responses --config "$VERIFY_CONFIG")
   echo ""
   echo "🧪 验证 release 安装的端到端工具链路..."
   if [ ! -f "$VERIFY_CONFIG" ]; then

package/scripts/install-verify.mjs

@@ -29,6 +29,7 @@ const state = {
 };
 let shuttingDown = false;
 let responsesSseParser = null;
+let requestAuthHeaderValue = 'Bearer install-verify';
 
 const manualSamples = {
   responses: path.join(repoRoot, 'scripts', 'verification', 'samples', 'openai-responses-list-local-files.json'),
@@ -40,6 +41,25 @@ function clonePayload(payload) {
   return JSON.parse(JSON.stringify(payload));
 }
 
+function normalizeString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function resolveConfigSecret(value) {
+  const trimmed = normalizeString(value);
+  if (!trimmed) {
+    return '';
+  }
+  const envMatch = trimmed.match(/^\$\{([A-Z0-9_]+)\}$/i);
+  if (envMatch) {
+    return normalizeString(process.env[envMatch[1]]);
+  }
+  if (/^[A-Z][A-Z0-9_]+$/.test(trimmed)) {
+    return normalizeString(process.env[trimmed]) || trimmed;
+  }
+  return trimmed;
+}
+
 function loadManualSample(kind) {
   const filePath = manualSamples[kind];
   if (!filePath) {
@@ -52,15 +72,34 @@ function loadManualSample(kind) {
 }
 
 async function importResponsesSseModule() {
-  const localSpecifiers = [
-    path.join(repoRoot, 'sharedmodule', 'llmswitch-core', 'dist', 'sse', 'sse-to-json', 'index.js')
-  ]
-    .filter((specifier) => fs.existsSync(specifier))
-    .map((specifier) => pathToFileURL(specifier).href);
-  for (const specifier of localSpecifiers) {
+  const npmSpecifiers = [
+    'rcc-llmswitch-core/dist/sse/sse-to-json/index.js',
+    'rcc-llmswitch-core/dist/v2/conversion/conversion-v3/sse/index.js'
+  ];
+  const resolvedNpmSpecifiers = npmSpecifiers
+    .map((specifier) => {
+      try {
+        return pathToFileURL(require.resolve(specifier)).href;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+  const localSpecifiers = npmSpecifiers
+    .map((specifier) => {
+      const relative = specifier.replace('rcc-llmswitch-core/dist/', '');
+      const localPath = path.join(repoRoot, 'sharedmodule', 'llmswitch-core', 'dist', relative);
+      if (fs.existsSync(localPath)) {
+        return pathToFileURL(localPath).href;
+      }
+      return null;
+    })
+    .filter(Boolean);
+  for (const specifier of [...resolvedNpmSpecifiers, ...localSpecifiers]) {
     try {
       return await import(specifier);
     } catch (error) {
+      if (resolvedNpmSpecifiers.includes(specifier)) continue;
       console.warn('⚠️ 加载 Responses SSE 模块失败:', error instanceof Error ? error.message : error);
     }
   }
@@ -407,12 +446,72 @@ function resolveHost(host) {
 }
 
 function resolveModel(config) {
+  const extractModelFromTarget = (target) => {
+    if (typeof target !== 'string') return '';
+    const normalized = target.trim();
+    if (!normalized) return '';
+    if (!normalized.includes('.')) return normalized;
+    const [, ...rest] = normalized.split('.');
+    const modelPart = rest.join('.');
+    return modelPart ? modelPart.split('__')[0] : '';
+  };
+
+  const resolveModelFromRouteEntry = (entry) => {
+    if (!entry) return '';
+    if (typeof entry === 'string') {
+      return extractModelFromTarget(entry);
+    }
+    if (typeof entry !== 'object') {
+      return '';
+    }
+    const directTarget =
+      (typeof entry.routeTarget === 'string' && entry.routeTarget) ||
+      (typeof entry.providerKey === 'string' && entry.providerKey) ||
+      (typeof entry.target === 'string' && entry.target);
+    const directModel = extractModelFromTarget(directTarget);
+    if (directModel) {
+      return directModel;
+    }
+    const weights = entry?.loadBalancing?.weights;
+    if (weights && typeof weights === 'object') {
+      for (const key of Object.keys(weights)) {
+        const weightedModel = extractModelFromTarget(key);
+        if (weightedModel) {
+          return weightedModel;
+        }
+      }
+    }
+    const targets = Array.isArray(entry?.targets) ? entry.targets : [];
+    for (const target of targets) {
+      const targetModel = resolveModelFromRouteEntry(target);
+      if (targetModel) {
+        return targetModel;
+      }
+    }
+    return '';
+  };
+
   try {
     const firstRoute = config?.virtualrouter?.routing?.default?.[0];
-    if (typeof firstRoute === 'string' && firstRoute.includes('.')) {
-      const [, ...rest] = firstRoute.split('.');
-      const modelPart = rest.join('.');
-      if (modelPart) return modelPart.split('__')[0];
+    const legacyModel = resolveModelFromRouteEntry(firstRoute);
+    if (legacyModel) {
+      return legacyModel;
+    }
+  } catch { /* ignore */ }
+  try {
+    const groups = config?.virtualrouter?.routingPolicyGroups;
+    const activeGroupId =
+      typeof config?.virtualrouter?.activeRoutingPolicyGroup === 'string' &&
+      config.virtualrouter.activeRoutingPolicyGroup.trim().length
+        ? config.virtualrouter.activeRoutingPolicyGroup.trim()
+        : '';
+    const group =
+      (activeGroupId && groups && typeof groups === 'object' ? groups[activeGroupId] : undefined) ||
+      (groups && typeof groups === 'object' ? groups[Object.keys(groups)[0]] : undefined);
+    const firstRoute = group?.routing?.default?.[0];
+    const v2Model = resolveModelFromRouteEntry(firstRoute);
+    if (v2Model) {
+      return v2Model;
     }
   } catch { /* ignore */ }
   try {
@@ -438,6 +537,17 @@ function detectPortPids(port) {
   }
 }
 
+function findAvailablePort(startPort) {
+  const base = Number.isInteger(startPort) && startPort > 0 ? startPort : 5520;
+  for (let offset = 0; offset < 64; offset += 1) {
+    const candidate = base + offset;
+    if (detectPortPids(candidate).length === 0) {
+      return candidate;
+    }
+  }
+  throw new Error(`无法找到可用验证端口（起始端口=${base}）`);
+}
+
 async function waitForHealth(baseUrl, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let lastMessage = '';
@@ -593,7 +703,7 @@ async function postJson(url, body, timeoutMs, extraHeaders = {}) {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        Authorization: 'Bearer install-verify',
+        Authorization: requestAuthHeaderValue,
         ...extraHeaders
       },
       body: JSON.stringify(body),
@@ -619,7 +729,7 @@ async function postSseRequest(url, body, timeoutMs, extraHeaders = {}) {
       headers: {
         'Content-Type': 'application/json',
         Accept: 'text/event-stream',
-        Authorization: 'Bearer install-verify',
+        Authorization: requestAuthHeaderValue,
         ...extraHeaders
       },
       body: JSON.stringify(body),
@@ -881,13 +991,21 @@ async function main() {
   console.log(`🧪 使用配置: ${configPath}`);
 
   const config = readJson(configPath);
-  const port = Number(config?.httpserver?.port ?? config?.server?.port ?? 5520);
+  const configuredApiKey = resolveConfigSecret(
+    config?.server?.apikey ?? config?.httpserver?.apikey ?? config?.apikey
+  );
+  requestAuthHeaderValue = configuredApiKey ? `Bearer ${configuredApiKey}` : 'Bearer install-verify';
+  const configuredPortRaw =
+    process.env.ROUTECODEX_INSTALL_VERIFY_PORT ||
+    process.env.RCC_INSTALL_VERIFY_PORT ||
+    config?.httpserver?.port ||
+    config?.server?.port ||
+    5520;
+  const configuredPort = Number(configuredPortRaw);
+  let port = Number.isInteger(configuredPort) && configuredPort > 0 ? configuredPort : 5520;
   const host = resolveHost(config?.httpserver?.host ?? config?.server?.host ?? '127.0.0.1');
-  const baseUrl = `http://${host}:${port}`;
-  state.baseUrl = baseUrl;
 
   const model = resolveModel(config);
-  console.log(`🔁 模型: ${model}, 端口: ${port}`);
   const buildRestartOnly = (() => {
     const raw = String(process.env.ROUTECODEX_BUILD_RESTART_ONLY ?? process.env.RCC_BUILD_RESTART_ONLY ?? '').trim().toLowerCase();
     return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
@@ -896,8 +1014,13 @@ async function main() {
   const listeners = detectPortPids(port);
   const reuseExistingServer = buildRestartOnly && listeners.length > 0;
   if (listeners.length && !reuseExistingServer) {
-    throw new Error(`端口 ${port} 已被使用 (PID: ${listeners.join(', ')}). 请先停止正在运行的 RouteCodex 实例再重试。`);
+    const originalPort = port;
+    port = findAvailablePort(port + 1);
+    console.log(`⚠️ 端口 ${originalPort} 已被占用 (PID: ${listeners.join(', ')})，改用临时验证端口 ${port}`);
   }
+  const baseUrl = `http://${host}:${port}`;
+  state.baseUrl = baseUrl;
+  console.log(`🔁 模型: ${model}, 端口: ${port}`);
   if (reuseExistingServer) {
     console.log(`ℹ build-restart-only: 检测到已运行服务 (PID: ${listeners.join(', ')})，复用现有实例进行验证。`);
   }
@@ -911,9 +1034,11 @@ async function main() {
   let cwd = repoRoot;
   if (launcher === 'cli') {
     command = cliBinary || 'routecodex';
-    commandArgs = ['start', '--config', configPath, '--exclusive'];
+    commandArgs = ['start', '--config', configPath, '--port', String(port), '--exclusive'];
     cwd = process.cwd();
     env.ROUTECODEX_CONFIG = configPath;
+    env.ROUTECODEX_PORT = String(port);
+    env.RCC_PORT = String(port);
   } else {
     command = process.execPath;
     commandArgs = [path.join(repoRoot, 'dist', 'index.js')];

package/scripts/link-global-llms-local.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, '..');
+const localLlms = path.join(projectRoot, 'sharedmodule', 'llmswitch-core');
+
+function parseArgs(argv) {
+  const out = {
+    packageNames: [],
+    requireTarget: false
+  };
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = String(argv[i] || '').trim();
+    if (!arg) continue;
+    if (arg === '--require-target') {
+      out.requireTarget = true;
+      continue;
+    }
+    if (arg === '--package' || arg === '-p') {
+      const value = String(argv[i + 1] || '').trim();
+      i += 1;
+      if (value) out.packageNames.push(value);
+      continue;
+    }
+    if (arg.startsWith('--package=')) {
+      const value = arg.slice('--package='.length).trim();
+      if (value) out.packageNames.push(value);
+      continue;
+    }
+  }
+  return out;
+}
+
+function npmRootGlobal() {
+  const res = spawnSync('npm', ['root', '-g'], { encoding: 'utf8' });
+  if ((res.status ?? 1) === 0) {
+    const value = String(res.stdout || '').trim();
+    if (value) return value;
+  }
+  const prefix = spawnSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8' });
+  const fallbackPrefix = (prefix.status ?? 1) === 0 ? String(prefix.stdout || '').trim() : '';
+  if (!fallbackPrefix) {
+    throw new Error('unable to resolve npm global root');
+  }
+  return path.join(fallbackPrefix, 'lib', 'node_modules');
+}
+
+function ensureLocalLlmsReady() {
+  if (!fs.existsSync(localLlms) || !fs.existsSync(path.join(localLlms, 'package.json'))) {
+    throw new Error(`local llmswitch-core not found: ${localLlms}`);
+  }
+  if (!fs.existsSync(path.join(localLlms, 'dist'))) {
+    throw new Error(`local llmswitch-core dist missing: ${path.join(localLlms, 'dist')}`);
+  }
+}
+
+function linkForPackage(globalRoot, packageName) {
+  const pkgRoot = path.join(globalRoot, ...packageName.split('/'));
+  if (!fs.existsSync(pkgRoot)) {
+    return { packageName, changed: false, skipped: true, reason: 'package-not-installed' };
+  }
+  const scopeDir = path.join(pkgRoot, 'node_modules', '@jsonstudio');
+  const linkPath = path.join(scopeDir, 'llms');
+  fs.mkdirSync(scopeDir, { recursive: true });
+  fs.rmSync(linkPath, { recursive: true, force: true });
+  fs.symlinkSync(localLlms, linkPath, 'junction');
+  const linkedTo = fs.readlinkSync(linkPath);
+  return { packageName, changed: true, skipped: false, linkPath, linkedTo };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const targets = args.packageNames.length > 0 ? args.packageNames : ['@jsonstudio/rcc', 'routecodex'];
+  ensureLocalLlmsReady();
+  const globalRoot = npmRootGlobal();
+  const results = targets.map((name) => linkForPackage(globalRoot, name));
+  const changed = results.filter((it) => it.changed);
+
+  if (args.requireTarget && changed.length <= 0) {
+    const detail = results
+      .map((it) => `${it.packageName}:${it.skipped ? it.reason : 'unknown'}`)
+      .join(', ');
+    throw new Error(`no eligible global package found to link @jsonstudio/llms (${detail})`);
+  }
+
+  for (const row of results) {
+    if (row.changed) {
+      console.log(
+        `[link-global-llms-local] linked ${row.packageName} -> ${row.linkPath} => ${row.linkedTo}`
+      );
+    } else if (row.skipped) {
+      console.log(`[link-global-llms-local] skip ${row.packageName} (${row.reason})`);
+    }
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  const reason = error instanceof Error ? error.message : String(error);
+  console.error(`[link-global-llms-local] failed: ${reason}`);
+  process.exit(1);
+}
+

package/scripts/link-llmswitch.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const mode = (process.argv[2] || 'link').toLowerCase();
+const root = process.cwd();
+const source = path.join(root, 'sharedmodule', 'llmswitch-core');
+const scopeDir = path.join(root, 'node_modules', '@jsonstudio');
+const dest = path.join(scopeDir, 'llms');
+
+function ensureNodeModules() {
+  if (!fs.existsSync(path.join(root, 'node_modules'))) {
+    fs.mkdirSync(path.join(root, 'node_modules'), { recursive: true });
+  }
+  if (!fs.existsSync(scopeDir)) {
+    fs.mkdirSync(scopeDir, { recursive: true });
+  }
+}
+
+function removeDest() {
+  try {
+    const stat = fs.lstatSync(dest);
+    if (stat.isSymbolicLink() || stat.isFile()) {
+      fs.unlinkSync(dest);
+    } else if (stat.isDirectory()) {
+      fs.rmSync(dest, { recursive: true, force: true });
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
+if (mode === 'link') {
+  if (!fs.existsSync(source)) {
+    console.error('[llmswitch-link] sharedmodule/llmswitch-core not found; did you clone sharedmodule repo?');
+    process.exit(1);
+  }
+  ensureNodeModules();
+  removeDest();
+  fs.symlinkSync(source, dest);
+  console.log('[llmswitch-link] linked node_modules/@jsonstudio/llms -> sharedmodule/llmswitch-core');
+  process.exit(0);
+}
+
+if (mode === 'unlink') {
+  if (fs.existsSync(dest)) {
+    removeDest();
+    console.log('[llmswitch-link] removed link at node_modules/@jsonstudio/llms');
+  } else {
+    console.log('[llmswitch-link] nothing to unlink');
+  }
+  process.exit(0);
+}
+
+console.error('[llmswitch-link] unknown mode. Use `link` (default) or `unlink`.');
+process.exit(1);