fuli-context 0.4.0 → 0.7.2

package/src/setup/container-runtime.js

@@ -86,7 +86,7 @@ export async function ensureContainerRuntime(options = {}, dependencies = {}) {
     throw containerRuntimeError(runtime, options.platform ?? process.platform);
   }
 
-  onProgress(`正在启动 ${runtime.desktop.label}，首次启动可能需要几分钟…`);
+  onProgress(`Starting ${runtime.desktop.label}; the first launch may take a few minutes...`);
   await launch(runtime.desktop, dependencies);
 
   const attempts = Math.max(1, Math.ceil(maxWaitMs / pollIntervalMs));
@@ -100,9 +100,9 @@ export async function ensureContainerRuntime(options = {}, dependencies = {}) {
   }
 
   throw new Error(
-    `${runtime.desktop?.label ?? runtime.label} 已启动，但容器引擎未在 ` +
-    `${Math.ceil(maxWaitMs / 1000)} 秒内就绪。请打开该应用查看错误，确认 docker info ` +
-    `可以成功后重新运行 fl setup。${detailSuffix(runtime.detail)}`
+    `${runtime.desktop?.label ?? runtime.label} started, but the container engine was not ready ` +
+    `within ${Math.ceil(maxWaitMs / 1000)} seconds. Open the application to inspect errors, ` +
+    `confirm that docker info succeeds, then run fl setup again.${detailSuffix(runtime.detail)}`
   );
 }
 
@@ -124,12 +124,14 @@ export function runDockerCompose(args, runtime = null, {
 
   const detail = safeProcessDetail(result, homeDir);
   if (/port is already allocated|address already in use|bind.+failed/i.test(detail)) {
-    throw new Error(`Fuli 需要的本地端口已被占用。${detailSuffix(detail)}`);
+    throw new Error(`A local port required by Fuli is already in use.${detailSuffix(detail)}`);
   }
   if (/cannot connect|connection refused|error during connect|docker daemon|\bEOF\b/i.test(detail)) {
-    throw new Error(`容器运行时在启动 Fuli Provider 时失去连接。${detailSuffix(detail)}`);
+    throw new Error(
+      `The container runtime disconnected while starting the Fuli Provider.${detailSuffix(detail)}`
+    );
   }
-  throw new Error(`Docker Compose 无法启动 Fuli Provider。${detailSuffix(detail)}`);
+  throw new Error(`Docker Compose could not start the Fuli Provider.${detailSuffix(detail)}`);
 }
 
 export function selectDockerEnvironment({
@@ -161,19 +163,21 @@ export function containerRuntimeError(runtime, platform = process.platform) {
   }
   if (runtime.status === 'missing-compose') {
     return new Error(
-      `已找到 Docker，但缺少 Docker Compose v2。请安装 Compose v2 后重新运行 fl setup。` +
+      'Docker was found, but Docker Compose v2 is missing. Install Compose v2, then run ' +
+      'fl setup again.' +
       detailSuffix(runtime.detail)
     );
   }
   if (runtime.explicitTarget) {
     return new Error(
-      `DOCKER_HOST 或 DOCKER_CONTEXT 指向的容器引擎不可用。请修复该配置并确认 ` +
-      `docker info 可以成功后重新运行 fl setup。${detailSuffix(runtime.detail)}`
+      'The container engine selected by DOCKER_HOST or DOCKER_CONTEXT is unavailable. Fix the ' +
+      `configuration, confirm that docker info succeeds, then run fl setup again.${detailSuffix(runtime.detail)}`
     );
   }
   return new Error(
-    `已找到 Docker 和 Compose，但容器引擎没有运行。请启动 Docker Desktop、` +
-    `Rancher Desktop 或当前 Docker 服务，确认 docker info 可以成功后重新运行 fl setup。` +
+    'Docker and Compose were found, but the container engine is not running. Start Docker ' +
+    'Desktop, Rancher Desktop, or the current Docker service; confirm that docker info succeeds; ' +
+    'then run fl setup again.' +
     detailSuffix(runtime.detail)
   );
 }
@@ -330,17 +334,17 @@ async function launchDesktopRuntime(desktop, { spawnProcess = spawn } = {}) {
 
 function missingRuntimeMessage(platform) {
   if (platform === 'darwin') {
-    return `未检测到可用的 Docker Compose 容器运行时。请安装并首次打开 Rancher Desktop ` +
-      `(${RANCHER_DOWNLOAD_URL}) 或 Docker Desktop (${DOCKER_DOWNLOAD_URL})，` +
-      `然后重新运行 fl setup。`;
+    return 'No usable Docker Compose container runtime was detected. Install and open Rancher ' +
+      `Desktop (${RANCHER_DOWNLOAD_URL}) or Docker Desktop (${DOCKER_DOWNLOAD_URL}), then run ` +
+      'fl setup again.';
   }
   if (platform === 'win32') {
-    return `未检测到可用的 Docker Compose 容器运行时。请先启用 WSL 2，再安装并首次打开 ` +
-      `Rancher Desktop (${RANCHER_DOWNLOAD_URL}) 或 Docker Desktop ` +
-      `(${DOCKER_DOWNLOAD_URL})，然后重新运行 fl setup。`;
+    return 'No usable Docker Compose container runtime was detected. Enable WSL 2, then install ' +
+      `and open Rancher Desktop (${RANCHER_DOWNLOAD_URL}) or Docker Desktop ` +
+      `(${DOCKER_DOWNLOAD_URL}), and run fl setup again.`;
   }
-  return `未检测到可用的 Docker Compose 容器运行时。请安装 Docker Engine + Compose v2，` +
-    `或 Rancher Desktop (${RANCHER_DOWNLOAD_URL})，然后重新运行 fl setup。`;
+  return 'No usable Docker Compose container runtime was detected. Install Docker Engine with ' +
+    `Compose v2, or Rancher Desktop (${RANCHER_DOWNLOAD_URL}), then run fl setup again.`;
 }
 
 function defaultDockerAvailable(env) {
@@ -372,7 +376,7 @@ function safeProcessDetail(result, homeDir) {
 }
 
 function detailSuffix(detail) {
-  return nonEmpty(detail) ? ` Docker 返回：${detail}` : '';
+  return nonEmpty(detail) ? ` Docker returned: ${detail}` : '';
 }
 
 function processSucceeded(result) {

package/src/setup/graph-runtime.js

@@ -1,4 +1,4 @@
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import {
   chmodSync,
@@ -15,38 +15,61 @@ import {
   ensureContainerRuntime,
   runDockerCompose
 } from './container-runtime.js';
+import {
+  discoverLanAddresses,
+  LAN_ACCESS_USERNAME,
+  lanConsoleUrls
+} from '../server/lan-access.js';
 import { readJsonFile, writeJsonFileAtomic } from '../storage/json-file.js';
+import {
+  DEFAULT_RUNTIME_SETTINGS,
+  managedProviderUrls,
+  normalizeRuntimeSettings,
+  runtimeSettingsWithOverrides,
+  writeRuntimeSettings
+} from '../system/runtime-settings.js';
 
 export {
   dockerInfoIndicatesDaemon,
   selectDockerEnvironment
 } from './container-runtime.js';
 
-const PERSONAL_PROVIDER_URL = 'http://127.0.0.1:8787';
-const WORKSPACE_PROVIDER_URL = 'http://127.0.0.1:8788';
-
-export const MANAGED_PERSONAL_PROVIDER_URL = PERSONAL_PROVIDER_URL;
-export const MANAGED_WORKSPACE_PROVIDER_URL = WORKSPACE_PROVIDER_URL;
-
 export async function ensureGraphRuntime(input, dependencies = {}) {
   const deps = graphDependencies(dependencies);
+  const runtimeSettings = normalizeRuntimeSettings(input.runtimeSettings ??
+    runtimeSettingsWithOverrides(DEFAULT_RUNTIME_SETTINGS, {
+      consolePort: input.port,
+      lanAccess: input.lan === true
+    }));
+  const urls = managedProviderUrls(runtimeSettings);
+  const lan = runtimeSettings.lanAccess;
+  const lanAddresses = lan ? deps.discoverLanAddresses() : [];
+  if (lan && lanAddresses.length === 0) {
+    throw new Error('No private IPv4 LAN address is available, so LAN mode cannot start.');
+  }
   const containerRuntime = await deps.ensureContainerRuntime({
     env: input.env ?? process.env,
     onProgress: input.onProgress
   });
   deps.ensureDirectory(input.paths.dataDir);
-  const secrets = ensureProviderSecrets(input.paths.graphEnvPath, deps);
+  const secrets = ensureProviderEnvironment(
+    input.paths.graphEnvPath,
+    runtimeSettings,
+    deps
+  );
+  deps.writeRuntimeSettings(input.paths.runtimeSettingsPath, runtimeSettings);
   deps.startProviders(input.paths, input.paths.graphEnvPath, {
     personalOnly: input.personalOnly === true,
     containerRuntime,
     ...(input.buildProviders === false ? { build: false } : {})
   });
-  await waitForProvider(PERSONAL_PROVIDER_URL, deps.fetch);
-  if (!input.personalOnly) await waitForProvider(WORKSPACE_PROVIDER_URL, deps.fetch);
+  await waitForProvider(urls.personal, deps.fetch);
+  if (!input.personalOnly) await waitForProvider(urls.workspace, deps.fetch);
 
   let config = deps.readConfig(input.paths.graphRuntimeConfigPath);
   if (!config) {
     config = await bootstrapGraph({
+      urls,
       personalSpaceName: input.personalSpaceName,
       secrets,
       personalOnly: input.personalOnly === true,
@@ -54,64 +77,105 @@ export async function ensureGraphRuntime(input, dependencies = {}) {
     });
     deps.writeConfig(input.paths.graphRuntimeConfigPath, config);
     deps.secureFile(input.paths.graphRuntimeConfigPath);
+  } else {
+    const synchronized = synchronizeManagedProviderUrls(config, urls, {
+      personalOnly: input.personalOnly === true
+    });
+    if (synchronized.changed) {
+      await reconcileManagedWorkspaceSubscriptions({
+        previousConfig: config,
+        nextConfig: synchronized.config,
+        personalUrl: urls.personal,
+        fetchImpl: deps.fetch
+      });
+      config = synchronized.config;
+      deps.writeConfig(input.paths.graphRuntimeConfigPath, config);
+      deps.secureFile(input.paths.graphRuntimeConfigPath);
+    }
   }
-  stopOwnedLegacyRuntime(input.paths, deps);
 
   if (input.noStart) return { status: 'initialized', url: null, pid: null };
   const existing = deps.readState(input.paths.graphRuntimeStatePath);
   if (isGraphRuntimeState(existing) && deps.isProcessAlive(existing.pid)) {
     const healthy = await deps.webHealth(existing.url, existing.pid, existing.version);
-    if (healthy && existing.port === input.port) {
-      return { status: 'running', url: existing.url, pid: existing.pid };
+    if (
+      healthy &&
+      existing.port === runtimeSettings.ports.console &&
+      exposureMatches(existing, { lan, lanAddresses })
+    ) {
+      return runtimeResult('running', existing);
     }
     if (!healthy) throw new Error('Recorded Fuli Graphiti runtime is not healthy');
     deps.stopProcess(existing.pid);
+    if (!await deps.waitForExit(existing.pid)) {
+      throw new Error('Fuli Graphiti console did not stop before changing exposure mode');
+    }
   }
+  const lanAccessToken = lan ? deps.createLanAccessToken() : null;
   const child = deps.spawnWebRuntime({
     paths: input.paths,
     nodePath: process.execPath,
-    port: input.port
+    port: runtimeSettings.ports.console,
+    lan,
+    lanAccessToken,
+    env: input.env ?? process.env
   });
-  const url = `http://127.0.0.1:${input.port}`;
+  const url = `http://127.0.0.1:${runtimeSettings.ports.console}`;
   if (!Number.isInteger(child.pid) || !await waitForWeb(url, child.pid, deps)) {
     if (Number.isInteger(child.pid)) deps.stopProcess(child.pid);
     throw new Error('Fuli Graphiti console could not start');
   }
-  deps.writeState(input.paths.graphRuntimeStatePath, {
-    version: 3,
+  const state = {
+    version: 4,
     pid: child.pid,
     url,
-    port: input.port,
+    port: runtimeSettings.ports.console,
+    runtimeSettings,
+    ...(lan
+      ? {
+          lan: true,
+          lanUrls: lanConsoleUrls(lanAddresses, runtimeSettings.ports.console)
+        }
+      : {}),
     managedProviders: input.personalOnly
       ? ['personal']
       : ['personal', 'development-workspace'],
     startedAt: new Date().toISOString()
-  });
-  return { status: 'started', url, pid: child.pid };
+  };
+  deps.writeState(input.paths.graphRuntimeStatePath, state);
+  deps.secureFile(input.paths.graphRuntimeStatePath);
+  return runtimeResult('started', state, lanAccessToken);
 }
 
-function ensureProviderSecrets(path, deps) {
-  if (deps.fileExists(path)) return parseEnv(deps.readText(path));
+function ensureProviderEnvironment(path, settings, deps) {
+  const previous = deps.fileExists(path) ? parseEnv(deps.readText(path)) : {};
   const values = {
-    FULI_PERSONAL_NEO4J_PASSWORD: secret(),
-    FULI_WORKSPACE_NEO4J_PASSWORD: secret(),
-    FULI_PERSONAL_BOOTSTRAP_TOKEN: secret(),
-    FULI_WORKSPACE_BOOTSTRAP_TOKEN: secret()
+    ...previous,
+    FULI_PERSONAL_NEO4J_PASSWORD: previous.FULI_PERSONAL_NEO4J_PASSWORD ?? secret(),
+    FULI_WORKSPACE_NEO4J_PASSWORD: previous.FULI_WORKSPACE_NEO4J_PASSWORD ?? secret(),
+    FULI_PERSONAL_BOOTSTRAP_TOKEN: previous.FULI_PERSONAL_BOOTSTRAP_TOKEN ?? secret(),
+    FULI_WORKSPACE_BOOTSTRAP_TOKEN: previous.FULI_WORKSPACE_BOOTSTRAP_TOKEN ?? secret(),
+    FULI_PERSONAL_NEO4J_HTTP_PORT: String(settings.ports.personalNeo4jHttp),
+    FULI_PERSONAL_NEO4J_BOLT_PORT: String(settings.ports.personalNeo4jBolt),
+    FULI_WORKSPACE_NEO4J_HTTP_PORT: String(settings.ports.workspaceNeo4jHttp),
+    FULI_WORKSPACE_NEO4J_BOLT_PORT: String(settings.ports.workspaceNeo4jBolt),
+    FULI_PERSONAL_PROVIDER_PORT: String(settings.ports.personalProvider),
+    FULI_WORKSPACE_PROVIDER_PORT: String(settings.ports.workspaceProvider)
   };
   const body = Object.entries(values).map(([key, value]) => `${key}=${value}`).join('\n') + '\n';
-  deps.writeText(path, body);
+  if (!deps.fileExists(path) || deps.readText(path) !== body) deps.writeText(path, body);
   deps.secureFile(path);
   return values;
 }
 
-async function bootstrapGraph({ personalSpaceName, secrets, personalOnly, fetchImpl }) {
+async function bootstrapGraph({ urls, personalSpaceName, secrets, personalOnly, fetchImpl }) {
   const personalIdentity = await bootstrapProvider(
-    PERSONAL_PROVIDER_URL,
+    urls.personal,
     secrets.FULI_PERSONAL_BOOTSTRAP_TOKEN,
     personalSpaceName,
     fetchImpl
   );
-  const personalSpace = await findOrCreateSpace(PERSONAL_PROVIDER_URL, {
+  const personalSpace = await findOrCreateSpace(urls.personal, {
     token: personalIdentity.access_token,
     name: personalSpaceName,
     kind: 'personal',
@@ -120,7 +184,7 @@ async function bootstrapGraph({ personalSpaceName, secrets, personalOnly, fetchI
   const config = {
     version: 1,
     personal: {
-      providerUrl: PERSONAL_PROVIDER_URL,
+      providerUrl: urls.personal,
       accessToken: personalIdentity.access_token,
       principalId: personalIdentity.principal_id,
       spaceId: personalSpace.id
@@ -130,35 +194,108 @@ async function bootstrapGraph({ personalSpaceName, secrets, personalOnly, fetchI
   if (personalOnly) return config;
 
   const workspaceIdentity = await bootstrapProvider(
-    WORKSPACE_PROVIDER_URL,
+    urls.workspace,
     secrets.FULI_WORKSPACE_BOOTSTRAP_TOKEN,
     personalSpaceName,
     fetchImpl
   );
-  const project = await findOrCreateSpace(WORKSPACE_PROVIDER_URL, {
+  const project = await findOrCreateSpace(urls.workspace, {
     token: workspaceIdentity.access_token,
     name: '工作',
     kind: 'project',
     fetchImpl
   });
-  await providerRequest(PERSONAL_PROVIDER_URL, '/v1/subscriptions', {
+  await providerRequest(urls.personal, '/v1/subscriptions', {
     token: personalIdentity.access_token,
     body: {
       personal_space_id: personalSpace.id,
       project_id: project.id,
-      provider_url: WORKSPACE_PROVIDER_URL,
+      provider_url: urls.workspace,
       project_name: project.name
     },
     fetchImpl
   });
   config.workspaces.push({
-      providerUrl: WORKSPACE_PROVIDER_URL,
-      accessToken: workspaceIdentity.access_token,
-      principalId: workspaceIdentity.principal_id
+    providerUrl: urls.workspace,
+    accessToken: workspaceIdentity.access_token,
+    principalId: workspaceIdentity.principal_id,
+    managedDevelopment: true
   });
   return config;
 }
 
+export function synchronizeManagedProviderUrls(config, urls, { personalOnly = true } = {}) {
+  const next = structuredClone(config);
+  let changed = next.personal?.providerUrl !== urls.personal;
+  next.personal.providerUrl = urls.personal;
+  if (!personalOnly) {
+    for (const workspace of next.workspaces ?? []) {
+      if (!isManagedWorkspace(workspace)) continue;
+      if (workspace.providerUrl !== urls.workspace || workspace.managedDevelopment !== true) {
+        changed = true;
+      }
+      workspace.providerUrl = urls.workspace;
+      workspace.managedDevelopment = true;
+    }
+  }
+  return { config: next, changed };
+}
+
+async function reconcileManagedWorkspaceSubscriptions({
+  previousConfig,
+  nextConfig,
+  personalUrl,
+  fetchImpl
+}) {
+  const previous = (previousConfig.workspaces ?? []).find(isManagedWorkspace);
+  const next = (nextConfig.workspaces ?? []).find(isManagedWorkspace);
+  if (!previous || !next || previous.providerUrl === next.providerUrl) return;
+  const query = new URLSearchParams({ personal_space_id: nextConfig.personal.spaceId });
+  const response = await fetchImpl(`${personalUrl}/v1/subscriptions?${query}`, {
+    headers: { authorization: `Bearer ${nextConfig.personal.accessToken}` }
+  });
+  if (!response.ok) throw new Error('Could not reconcile managed workspace subscriptions');
+  const subscriptions = await response.json();
+  for (const subscription of subscriptions.filter(
+    (item) => item.provider_url === previous.providerUrl
+  )) {
+    const removal = new URLSearchParams({
+      personal_space_id: nextConfig.personal.spaceId,
+      provider_url: previous.providerUrl
+    });
+    const removed = await fetchImpl(
+      `${personalUrl}/v1/subscriptions/${encodeURIComponent(subscription.project_id)}?${removal}`,
+      {
+        method: 'DELETE',
+        headers: { authorization: `Bearer ${nextConfig.personal.accessToken}` }
+      }
+    );
+    if (!removed.ok) throw new Error('Could not remove the previous managed workspace port');
+    await providerRequest(personalUrl, '/v1/subscriptions', {
+      token: nextConfig.personal.accessToken,
+      body: {
+        personal_space_id: nextConfig.personal.spaceId,
+        project_id: subscription.project_id,
+        provider_url: next.providerUrl,
+        project_name: subscription.project_name
+      },
+      fetchImpl
+    });
+  }
+}
+
+function isManagedWorkspace(workspace) {
+  if (workspace?.managedDevelopment === true) return true;
+  try {
+    const url = new URL(workspace?.providerUrl);
+    return url.protocol === 'http:' &&
+      ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(url.hostname) &&
+      url.port === '8788';
+  } catch {
+    return false;
+  }
+}
+
 async function bootstrapProvider(url, bootstrapToken, principalName, fetchImpl) {
   const response = await fetchImpl(`${url}/v1/bootstrap`, {
     method: 'POST',
@@ -217,7 +354,7 @@ async function waitForProvider(url, fetchImpl) {
 async function waitForWeb(url, pid, deps) {
   for (let attempt = 0; attempt < 100; attempt += 1) {
     if (!deps.isProcessAlive(pid)) return false;
-    if (await deps.webHealth(url, pid, 3)) return true;
+    if (await deps.webHealth(url, pid, 4)) return true;
     await delay(100);
   }
   return false;
@@ -250,14 +387,19 @@ function spawnWebRuntime(input) {
   mkdirSync(dirname(input.paths.logPath), { recursive: true });
   const log = openSync(input.paths.logPath, 'a');
   try {
-    const child = spawn(input.nodePath, [
+    const args = [
       input.paths.serverPath,
       '--runtime-config', input.paths.graphRuntimeConfigPath,
       '--port', String(input.port)
-    ], {
+    ];
+    if (input.lan) args.push('--lan');
+    const child = spawn(input.nodePath, args, {
       detached: true,
       windowsHide: true,
-      stdio: ['ignore', log, log]
+      stdio: ['ignore', log, log],
+      env: input.lan
+        ? { ...input.env, FULI_LAN_ACCESS_TOKEN: input.lanAccessToken }
+        : input.env
     });
     child.unref();
     return child;
@@ -266,13 +408,6 @@ function spawnWebRuntime(input) {
   }
 }
 
-function stopOwnedLegacyRuntime(paths, deps) {
-  deps.stopLegacyService();
-  const state = deps.readState(paths.statePath);
-  if (state?.version !== 1 || state.dbPath !== paths.dbPath || !Number.isInteger(state.pid)) return;
-  if (deps.isProcessAlive(state.pid)) deps.stopProcess(state.pid);
-}
-
 function graphDependencies(overrides) {
   return {
     fetch: globalThis.fetch,
@@ -283,6 +418,7 @@ function graphDependencies(overrides) {
     ensureDirectory: (path) => mkdirSync(path, { recursive: true }),
     readConfig: (path) => readJsonFile(path, null),
     writeConfig: writeJsonFileAtomic,
+    writeRuntimeSettings,
     readState: (path) => readJsonFile(path, null),
     writeState: writeJsonFileAtomic,
     ensureContainerRuntime,
@@ -290,8 +426,10 @@ function graphDependencies(overrides) {
     spawnWebRuntime,
     isProcessAlive,
     stopProcess,
-    stopLegacyService,
     webHealth: checkLocalConsoleHealth,
+    discoverLanAddresses,
+    createLanAccessToken: secret,
+    waitForExit: waitForProcessExit,
     ...overrides
   };
 }
@@ -319,17 +457,32 @@ export async function checkLocalConsoleHealth(url, expectedPid, stateVersion = 3
 }
 
 function isGraphRuntimeState(state) {
-  return (state?.version === 2 || state?.version === 3) &&
+  return (state?.version === 2 || state?.version === 3 || state?.version === 4) &&
     Number.isInteger(state.pid) && typeof state.url === 'string';
 }
 
-function stopLegacyService() {
-  if (process.platform !== 'darwin') return;
-  spawnSync('launchctl', ['remove', 'dev.jevonscode.fuli.local'], {
-    encoding: 'utf8',
-    windowsHide: true,
-    stdio: 'ignore'
-  });
+function exposureMatches(state, { lan }) {
+  if ((state.lan === true) !== lan) return false;
+  if (!lan) return true;
+  // A repeated explicit LAN start rotates the in-memory access code.
+  return false;
+}
+
+function runtimeResult(status, state, lanAccessToken = null) {
+  const result = { status, url: state.url, pid: state.pid };
+  if (state.lan !== true) return result;
+  if (typeof lanAccessToken !== 'string' || lanAccessToken.length < 16) {
+    throw new Error('LAN runtime started without a valid access code');
+  }
+  return {
+    ...result,
+    lan: true,
+    lanUrls: [...state.lanUrls],
+    lanAccess: {
+      username: LAN_ACCESS_USERNAME,
+      accessCode: lanAccessToken
+    }
+  };
 }
 
 function parseEnv(body) {
@@ -355,6 +508,14 @@ function stopProcess(pid) {
   try { process.kill(pid, 'SIGTERM'); } catch { /* already stopped */ }
 }
 
+async function waitForProcessExit(pid) {
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    if (!isProcessAlive(pid)) return true;
+    await delay(100);
+  }
+  return false;
+}
+
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/src/setup/node-runtime.js

@@ -4,14 +4,14 @@ export function assertSupportedNodeVersion(version = process.versions.node) {
   const parsed = parseNodeVersion(version);
   if (compareVersions(parsed, MINIMUM_NODE_VERSION) >= 0) return;
   throw new Error(
-    `fl setup 需要 Node.js 24.12 或更高版本；当前为 ${version}。` +
-    `请升级 Node.js 后重新运行 fl setup。`
+    `fl setup requires Node.js 24.12 or later; the current version is ${version}. ` +
+    'Upgrade Node.js, then run fl setup again.'
   );
 }
 
 function parseNodeVersion(value) {
   const match = String(value).match(/^v?(\d+)\.(\d+)\.(\d+)/);
-  if (!match) throw new Error(`无法识别 Node.js 版本：${value}`);
+  if (!match) throw new Error(`Could not parse Node.js version: ${value}`);
   return match.slice(1).map(Number);
 }
 

package/src/setup/options.js

@@ -1,5 +1,3 @@
-import { DEFAULT_FULI_PORT } from '../defaults.js';
-
 const VALUE_OPTIONS = Object.freeze({
   '--data-dir': 'dataDir',
   '--personal-space': 'personalSpaceName',
@@ -26,8 +24,8 @@ export function parseUpdateOptions(args = []) {
 function parseSetupLikeOptions(args, command) {
   const result = {
     dataDir: null,
-    personalSpaceName: '我',
-    port: DEFAULT_FULI_PORT,
+    personalSpaceName: 'Personal',
+    port: null,
     yes: false,
     codexOnly: false,
     skipAgents: false,

package/src/setup/paths.js

@@ -16,19 +16,34 @@ export function resolveSetupPaths({
   const root = resolve(packageRoot);
   return {
     dataDir: resolvedDataDir,
-    dbPath: join(resolvedDataDir, 'context.db'),
     graphEnvPath: join(resolvedDataDir, 'graph-provider.env'),
     graphRuntimeConfigPath: join(resolvedDataDir, 'graph-runtime.json'),
     graphRuntimeStatePath: join(resolvedDataDir, 'graph-runtime-state.json'),
+    runtimeSettingsPath: join(resolvedDataDir, 'runtime-settings.json'),
+    externalKnowledgeRegistryPath: join(
+      resolvedDataDir,
+      'external-knowledge',
+      'bindings.json'
+    ),
+    externalKnowledgeConflictPolicyPath: join(
+      resolvedDataDir,
+      'external-knowledge',
+      'conflict-policies.json'
+    ),
+    externalKnowledgeConnectorDir: join(
+      resolvedDataDir,
+      'external-knowledge',
+      'connectors'
+    ),
     backupDir: join(resolvedDataDir, 'backups', 'agents'),
     logPath: join(resolvedDataDir, 'logs', 'runtime.log'),
-    statePath: join(resolvedDataDir, 'runtime.json'),
     serverPath: join(root, 'src', 'server.js'),
     mcpServerPath: join(root, 'src', 'mcp-server.js'),
     graphSetupPath: join(root, 'src', 'graphiti', 'setup.js'),
     graphComposePath: join(root, 'compose.graphiti.yml'),
     sessionSkillPath: join(root, 'skills', 'capturing-session-knowledge'),
-    projectSkillPath: join(root, 'skills', 'grilling-project')
+    projectSkillPath: join(root, 'skills', 'grilling-project'),
+    reviewSkillPath: join(root, 'skills', 'flreview')
   };
 }
 

package/src/setup/review-skill-adapters.js

@@ -0,0 +1,49 @@
+const REVIEW_SKILL_NAME = 'flreview';
+
+// Keep every host-specific difference for the review Skill here. The shared
+// SKILL.md intentionally contains no Codex/Claude/Cursor branching.
+const ADAPTERS = Object.freeze({
+  codex: Object.freeze({
+    root: ['.agents', 'skills'],
+    nativeInvocation: '$flreview',
+    needsCommandBridge: true
+  }),
+  'claude-code': Object.freeze({
+    root: ['.claude', 'skills'],
+    nativeInvocation: '/flreview',
+    needsCommandBridge: false
+  }),
+  cursor: Object.freeze({
+    root: ['.cursor', 'skills'],
+    nativeInvocation: '/flreview',
+    needsCommandBridge: false
+  })
+});
+
+export function adaptAgentForReviewSkill(agent, { homeDir, pathApi }) {
+  const adapter = adapterFor(agent.id);
+  return {
+    ...agent,
+    reviewSkillPath: pathApi.join(homeDir, ...adapter.root, REVIEW_SKILL_NAME),
+    reviewSkillTrigger: reviewSkillTrigger(agent.id)
+  };
+}
+
+export function reviewSkillTrigger(agentId) {
+  const adapter = adapterFor(agentId);
+  return {
+    userCommand: '/flreview',
+    nativeInvocation: adapter.nativeInvocation,
+    needsCommandBridge: adapter.needsCommandBridge
+  };
+}
+
+export function codexReviewCommandBridge() {
+  return 'Exact `/flreview`: load installed `flreview` Skill.';
+}
+
+function adapterFor(agentId) {
+  const adapter = ADAPTERS[agentId];
+  if (!adapter) throw new TypeError(`Unsupported review Skill agent: ${agentId}`);
+  return adapter;
+}