openxiangda 1.0.268 → 1.0.269

package/README.md

@@ -22,6 +22,21 @@ Normal OpenXiangda app development uses platform-user login tokens through `/ope
 
 Private platform routing is fixed: backend APIs are under `/service`, platform management is under `/platform`, and app runtime access is under `/view`. Passing a root domain such as `https://platform.example.com/` to the CLI is supported; OpenXiangda stores the API base as `https://platform.example.com/service`.
 
+## 升级到 OpenXiangda 2.0
+
+建议评估升级到 OpenXiangda 2.0；新应用优先使用 V2，现有应用先确认能力覆盖、迁移成本与验收方案。准备 Node.js 24+，安装最新统一入口：
+
+```bash
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+# 进入原 V1 项目，使用新版全局入口
+openxiangda version --json
+openxiangda migrate assess --to v2 --json
+```
+
+`latest` / `stable-v2` 是 V2 稳定渠道，`legacy-v1` 是 V1 维护渠道。统一入口继续用原项目的 V1 引擎；不会自动迁移配置、数据或流程。V1 项目用 `openxiangda update install --target workspace` 更新同代维护版；全局入口用 `--target launcher` 更新。项目锁定的 V1 CLI 不提供 `migrate` 命令，评估时使用新版全局命令。
+
+版本查询、更新检查/安装、Skill 安装后会展示建议；JSON 调用通过 `migrationAdvice` 字段提供同样信息。CLI、Skill、MCP 如何安装、刷新以及配置客户端，见[统一安装升级说明](https://github.com/1377385356/openxiangda/blob/master/docs/getting-started.md#upgrade)。工具更新与应用迁移分别执行。
+
 ## OpenXiangda 1.x Delivery V2 (maintenance)
 
 New workspaces declare `deliveryVersion: 2`. The release flow is intentionally
@@ -150,7 +165,7 @@ openxiangda inspect app --profile dev --json
 openxiangda app snapshot APP_XXXX --profile dev --json
 ```
 
-User tokens are stored in `~/.openxiangda/profiles.json` with `0600` permissions. Shared workspace environment values, including `APP_OSS_*`, can live in `~/.openxiangda/.env` and are inherited by new workspaces. Project `.env` files still work and override the global defaults. Project state is stored in `.openxiangda/state.json` and contains only durable profile-specific resource IDs and environment bindings; volatile candidate/deployment progress lives in the private `.openxiangda/releases/` journal so a release does not dirty the reviewed Git state. Durable CLI writes use a workspace lock plus atomic merge/rename so concurrent processes do not truncate another profile's state.
+User tokens are stored in the current workspace `.openxiangda/profiles.json` with `0600` permissions and automatic Git ignore rules. Global profiles are no longer read or merged; sign in again in each project after upgrading. Use `login --cwd <directory>` to select a new project explicitly. Shared workspace environment values, including `APP_OSS_*`, can live in `~/.openxiangda/.env` and are inherited by new workspaces. Project `.env` files still work and override the global defaults. Project state is stored in `.openxiangda/state.json` and contains only durable profile-specific resource IDs and environment bindings; volatile candidate/deployment progress lives in the private `.openxiangda/releases/` journal so a release does not dirty the reviewed Git state. Durable CLI writes use a workspace lock plus atomic merge/rename so concurrent processes do not truncate another profile's state.
 
 An environment-managed workspace keeps one logical application with independent `preproduction` and `production` targets. Each target owns its own `appType`, resource IDs, release heads, data, and side-effect policy; IDs must never be copied across targets. `release ship` always executes the same ordered candidate → preproduction → production protocol. The normal first invocation seals the candidate, deploys only to preproduction, and stops at `awaiting_production_confirmation`; a later invocation with `--confirm-production` promotes it. For an explicitly authorized emergency, supplying `--confirm-production` on the first invocation runs both phases in one command without bypassing preproduction, CAS, evidence, or production confirmation. Candidate sealing covers source, `public/`, build controls/scripts, stable environment/resource bindings, and target-specific hashed Runtime artifacts. Both deployments upload those artifacts with `--no-build`; Backend, Runtime, and Root children all retain the sealed candidate `sourceRevision`, even when promotion starts from a later clean descendant mainline commit. Each deployment is completed with evidence and reaches terminal `succeeded`, so it cannot leave the target slot blocked. Unrelated commits may land on authoritative mainline between phases only while the sealed commit remains an ancestor and every sealed input/binding/artifact still validates. Real human acceptance remains the recommended default and `--acceptance-note` records it. For audited historical-lineage adoption or reviewed Backend manifest replacement, the existing paired flags and exact-scope gates remain mandatory. Supported configuration resources use exact `resourceSelectors`; unknown, wildcard, destructive, and genuinely unscoped generic resources remain blocked. Lower-level candidate/deploy/test/fail/promote commands are recovery primitives. `release fail` requires an explicit preproduction target, deployment ID, and audit message; it verifies the deployment belongs to that preproduction environment before writing optional code/details to the platform failure audit. Direct `release publish` is retained only for legacy unmanaged workspaces.
 
@@ -685,3 +700,5 @@ Skill migration plan: [docs/skill-refactor-plan.md](docs/skill-refactor-plan.md)
 Release isolation and speed roadmap: [docs/release-isolation-and-speed-roadmap.md](docs/release-isolation-and-speed-roadmap.md).
 
 Reproduced concurrency incidents and regression invariants: [docs/release-concurrency-incident-matrix.md](docs/release-concurrency-incident-matrix.md).
+
+平台登录态只使用当前工作区的 `.openxiangda/profiles.json`，不再读取或合并用户主目录的全局 profiles。升级后请进入每个项目运行 `openxiangda login <platform-url>`；子目录沿最近应用根目录定位，不跨嵌套应用或 Git 边界。登录文件及临时文件会自动加入忽略规则，请勿提交或打包。新项目先用 `openxiangda login <platform-url> --cwd <directory>` 在目标目录登录，再在该目录运行 `openxiangda workspace init`。

package/lib/cli.js

@@ -7,7 +7,7 @@ const { spawn, spawnSync } = require('child_process');
 const { pathToFileURL } = require('url');
 const esbuild = require('esbuild');
 const {
-  CONFIG_FILE,
+  getConfigFile,
   GLOBAL_ENV_FILE,
   PROJECT_STATE_FILE,
   getProfile,
@@ -115,6 +115,7 @@ const {
 } = require('./resource-binding-contract');
 const { getSkillStatusReport, installSkills } = require('./skills');
 const { resolveUpdateTarget, buildGenerationUpdateCommand } = require('./generation-update');
+const { migrationAdvice, printMigrationAdvice } = require('./migration-advice');
 const {
   assertOrClaimWorktreeOwner,
   claimWorktreeOwner,
@@ -233,7 +234,12 @@ const genericGitBasePlanCache = new Map();
 async function main(argv) {
   let commandError = null;
   try {
-    return await mainImpl(argv);
+    const result = await mainImpl(argv);
+    const [command, action] = argv;
+    if (!argv.some(value => value === '--json' || value.startsWith('--json=')) && (!command || ['version', '--version', '-v', 'help', '--help', '-h', 'update'].includes(command) || command === 'skill' && ['install', 'bootstrap'].includes(action))) {
+      printMigrationAdvice();
+    }
+    return result;
   } catch (error) {
     commandError = error;
     throw error;
@@ -319,12 +325,12 @@ function printHelp() {
 
 Usage:
   openxiangda version [--json]
-  openxiangda login <platform-url> [--profile name]
-  openxiangda update check|install [--json] [--registry https://registry.npmjs.org]
+  openxiangda login <platform-url> [--profile name] [--cwd directory]
+  openxiangda update check|install [--target workspace|launcher] [--json] [--registry https://registry.npmjs.org]
   openxiangda platform add <name> <platform-url>
   openxiangda platform list
   openxiangda platform use <name>
-  openxiangda auth status|refresh|logout [--profile name]
+  openxiangda auth status|refresh|logout [--profile name] [--cwd directory]
   openxiangda doctor [--profile name] [--app-type APP_XXX] [--release] [--json]
   openxiangda contract list|explain <contract-name> [--json]
   openxiangda policy show|check|render [--json]
@@ -519,6 +525,7 @@ async function version(args) {
       atomicActivation: APP_FUNCTION_SECRET_CAPABILITIES.atomicActivation,
     },
     updateCheckCommand: 'openxiangda update check --json',
+    migrationAdvice: migrationAdvice(),
   };
   if (flags.json) return writeJson(result);
   print(CURRENT_VERSION);
@@ -529,7 +536,7 @@ async function update(args) {
   const parsedArgs = requestedSubcommand === args[0] ? args.slice(1) : args;
   const { flags } = parseArgs(parsedArgs);
   if (wantsSubcommandHelp(requestedSubcommand, flags)) {
-    print('用法: openxiangda update check|install [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
+    print('用法: openxiangda update check|install [--target workspace|launcher] [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
     return;
   }
   const registry = normalizeNpmRegistry(flags.registry || OFFICIAL_NPM_REGISTRY);
@@ -557,7 +564,7 @@ async function update(args) {
     return;
   }
 
-  fail('用法: openxiangda update check|install [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
+  fail('用法: openxiangda update check|install [--target workspace|launcher] [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
 }
 
 function normalizeNpmRegistry(value) {
@@ -586,6 +593,7 @@ function checkOpenXiangdaUpdate(registry, selection = resolveUpdateTarget()) {
     skillInstallCommand: 'openxiangda skill install',
     compatibilityCheckCommand: 'openxiangda commands --json',
     checkedAt: new Date().toISOString(),
+    migrationAdvice: migrationAdvice(),
     notes: [
       'Use the official npm registry for OpenXiangda updates; domestic mirrors may lag.',
       'After updating the package, refresh OpenXiangda skills so AI guidance matches the CLI version.',
@@ -766,6 +774,7 @@ async function installOpenXiangdaUpdate(registry, options = {}) {
     registry: plan.registry,
     installCommand: `npm ${npmArgs.join(' ')}`,
     installed: true,
+    migrationAdvice: migrationAdvice(),
     durationMs: installResult.durationMs,
     cacheMode: 'prefer-offline',
     timeoutSeconds: plan.timeoutSeconds,
@@ -9444,7 +9453,7 @@ async function platform(args) {
     print('用法: openxiangda platform add|list|use|remove');
     return;
   }
-  const config = loadConfig();
+  const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
 
   if (subcommand === 'prepare') {
     const result = prepareDependencyCapsule({
@@ -9549,10 +9558,10 @@ async function login(args) {
     positional[0] === '--help' ||
     positional[0] === '-h'
   ) {
-    print('用法: openxiangda login <platform-url> [--profile name] [--no-open] [--json]');
+    print('用法: openxiangda login <platform-url> [--profile name] [--cwd directory] [--no-open] [--json]');
     return;
   }
-  const config = loadConfig();
+  const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
   const rawUrl = positional[0];
   const profileName = flags.profile || config.currentProfile || 'default';
   let profile = config.profiles[profileName] || { name: profileName };
@@ -9567,7 +9576,7 @@ async function login(args) {
   }
 
   if (!profile.baseUrl) {
-    fail('缺少平台地址。用法: openxiangda login <platform-url> [--profile name]');
+    fail('缺少平台地址。用法: openxiangda login <platform-url> [--profile name] [--cwd directory]');
   }
 
   const sessionPayload = await requestJson(
@@ -9666,12 +9675,12 @@ async function auth(args) {
   const [subcommand, ...rest] = args;
   const { flags } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
-    print('用法: openxiangda auth status|refresh|logout [--profile name] [--json]');
+    print('用法: openxiangda auth status|refresh|logout [--profile name] [--cwd directory] [--json]');
     return;
   }
 
   if (subcommand === 'status') {
-    const config = loadConfig();
+    const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
     const { profileName, profile } = getProfile(config, flags.profile);
     if (!profile.token?.accessToken) {
       print(`未登录: ${profileName} (${profile.baseUrl})`);
@@ -9689,7 +9698,7 @@ async function auth(args) {
   }
 
   if (subcommand === 'refresh') {
-    const config = loadConfig();
+    const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
     const profileName = flags.profile || config.currentProfile;
     if (!profileName) fail('未选择平台 profile');
     const data = await refreshProfile(config, profileName);
@@ -9700,7 +9709,7 @@ async function auth(args) {
   }
 
   if (subcommand === 'logout') {
-    const config = loadConfig();
+    const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
     const { profileName, profile } = getProfile(config, flags.profile);
     if (profile.token?.accessToken) {
       try {
@@ -9718,7 +9727,7 @@ async function auth(args) {
     return;
   }
 
-  fail('用法: openxiangda auth status|refresh|logout [--profile name]');
+  fail('用法: openxiangda auth status|refresh|logout [--profile name] [--cwd directory]');
 }
 
 async function env(args) {
@@ -9735,7 +9744,8 @@ async function env(args) {
   const currentState = profileName ? state.profiles?.[profileName] : null;
   const oss = summarizeOssEnv(globalEnv);
   const data = {
-    configFile: CONFIG_FILE,
+    configFile: getConfigFile(config),
+    sessionScope: 'workspace',
     globalEnvFile: GLOBAL_ENV_FILE,
     globalEnvExists: fs.existsSync(GLOBAL_ENV_FILE),
     projectStateFile: path.join(process.cwd(), PROJECT_STATE_FILE),
@@ -10198,7 +10208,9 @@ async function workspace(args) {
     printWorkspaceHelp();
     return;
   }
-  const config = loadConfig();
+  const config = subcommand === 'init'
+    ? loadConfig(path.resolve(positional[0] || process.cwd()), { exact: true })
+    : loadConfig();
 
   if (subcommand === 'ownership' || subcommand === 'owner') {
     const action = positional[0] || 'status';
@@ -17064,7 +17076,7 @@ async function commands(args) {
     commands: [
       'version [--json]',
       'login <platform-url> [--profile name]',
-      'update check|install',
+      'update check|install [--target workspace|launcher] [--json]',
       'platform add|list|use|remove',
       'auth status|refresh|logout',
       'doctor [--profile name] [--app-type APP_XXX] [--release]',
@@ -17160,6 +17172,7 @@ async function skill(args) {
 
   if (subcommand === 'install') {
     const result = installSkills(options);
+    result.migrationAdvice = migrationAdvice();
     if (flags.json) return writeJson(result);
     printSkillInstallReport(result);
     return;
@@ -17178,6 +17191,7 @@ async function skill(args) {
       force: Boolean(flags.force),
       dryRun: Boolean(flags['dry-run']),
     });
+    result.migrationAdvice = migrationAdvice();
     if (flags.json) return writeJson(result);
     printSkillBootstrapReport(result);
     return;
@@ -22492,7 +22506,7 @@ function runGenericResourceGitBasePreflight({
         copyProjectState: true,
       },
       ({ buildRoot, buildEnv, tempRoot }) => {
-        const isolatedHome = prepareReadonlyGitBasePlanHome(tempRoot);
+        const isolatedHome = prepareReadonlyGitBasePlanHome(tempRoot, buildRoot);
         const childEnv = {
           ...buildEnv,
           HOME: isolatedHome,
@@ -22628,8 +22642,9 @@ function runGenericResourceGitBasePreflight({
   };
 }
 
-function prepareReadonlyGitBasePlanHome(tempRoot) {
-  if (!fs.existsSync(CONFIG_FILE)) {
+function prepareReadonlyGitBasePlanHome(tempRoot, buildRoot) {
+  const configSource = getConfigFile();
+  if (!fs.existsSync(configSource)) {
     const error = new Error(
       'SOURCE_BASE_PLAN_FAILED: 当前 profile 配置不存在，无法执行隔离 Git 基线 plan'
     );
@@ -22637,10 +22652,11 @@ function prepareReadonlyGitBasePlanHome(tempRoot) {
     throw error;
   }
   const home = path.join(tempRoot, 'plan-home');
-  const configDir = path.join(home, '.openxiangda');
+  const configDir = path.join(buildRoot, '.openxiangda');
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
   const configFile = path.join(configDir, 'profiles.json');
   fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
-  fs.copyFileSync(CONFIG_FILE, configFile);
+  fs.copyFileSync(configSource, configFile);
   try {
     fs.chmodSync(configFile, 0o400);
   } catch {

package/lib/config.js

@@ -9,7 +9,6 @@ const CONFIG_FILE = path.join(CONFIG_DIR, 'profiles.json');
 const GLOBAL_ENV_FILE = path.join(CONFIG_DIR, '.env');
 const PROJECT_DIR = '.openxiangda';
 const PROJECT_STATE_FILE = path.join(PROJECT_DIR, 'state.json');
-const LEGACY_PROJECT_CONFIG_FILE = path.join(PROJECT_DIR, 'profiles.json');
 const PROJECT_STATE_LOCK_TIMEOUT_MS = 15_000;
 const PROJECT_STATE_STALE_LOCK_MS = 30_000;
 const projectStateBaselines = new WeakMap();
@@ -47,74 +46,78 @@ function normalizeConfig(config) {
   };
 }
 
-function mergeConfigs(...configs) {
-  const merged = emptyConfig();
-  for (const config of configs) {
-    if (!config) continue;
-    const normalized = normalizeConfig(config);
-    merged.version = normalized.version || merged.version;
-    if (normalized.currentProfile) {
-      merged.currentProfile = normalized.currentProfile;
-    }
-    for (const [name, profile] of Object.entries(normalized.profiles)) {
-      merged.profiles[name] = mergeProfile(merged.profiles[name], profile);
-    }
-  }
-  return normalizeConfig(merged);
-}
+const configPaths = new WeakMap();
 
-function mergeProfile(previous = {}, next = {}) {
-  const merged = {
-    ...previous,
-    ...next,
-  };
-  const baseUrlChanged =
-    previous.baseUrl && next.baseUrl && previous.baseUrl !== next.baseUrl;
-  for (const key of ['token', 'user', 'tenant']) {
-    if (
-      !baseUrlChanged &&
-      !Object.prototype.hasOwnProperty.call(next, key) &&
-      previous[key] != null
-    ) {
-      merged[key] = previous[key];
-    }
+function workspaceRoot(cwd = process.cwd()) {
+  const start = path.resolve(cwd);
+  if (!fs.existsSync(start)) return start;
+  let directory = start;
+  while (directory !== os.homedir()) {
+    if (['app-workspace.config.ts', 'app-workspace.config.js', 'openxiangda.config.ts', '.openxiangda/profiles.json']
+      .some(file => fs.existsSync(path.join(directory, file)))) return directory;
+    if (fs.existsSync(path.join(directory, '.git'))) return start;
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
   }
-  return merged;
+  return start;
 }
 
-function isConfigEqual(left, right) {
-  return JSON.stringify(normalizeConfig(left)) === JSON.stringify(normalizeConfig(right));
+function getConfigFile(config, cwd = process.cwd()) {
+  return configPaths.get(config) || path.join(workspaceRoot(cwd), PROJECT_DIR, 'profiles.json');
 }
 
-function loadConfig(cwd = process.cwd()) {
-  ensureUserConfigDir();
-  const globalConfig = readJson(CONFIG_FILE, null);
-  const legacyConfig = readJson(path.join(cwd, LEGACY_PROJECT_CONFIG_FILE), null);
-
-  if (legacyConfig?.profiles && Object.keys(legacyConfig.profiles).length > 0) {
-    const migrated = mergeConfigs(legacyConfig, globalConfig);
-    if (!globalConfig || !isConfigEqual(globalConfig, migrated)) {
-      saveConfig(migrated);
+function assertConfigFile(file) {
+  if (file === CONFIG_FILE) throw new Error('请进入项目工作区后登录；不再使用用户主目录的全局登录态');
+  for (const target of [path.dirname(file), file]) {
+    try {
+      const info = fs.lstatSync(target);
+      if (info.isSymbolicLink() || (target === file && (!info.isFile() || info.size > 1024 * 1024))) {
+        throw new Error(`工作区登录态必须是普通文件: ${file}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
     }
-    return migrated;
   }
+}
 
-  return normalizeConfig(globalConfig);
+function loadConfig(cwd = process.cwd(), options = {}) {
+  const file = options.exact
+    ? path.join(path.resolve(cwd), PROJECT_DIR, 'profiles.json')
+    : getConfigFile(null, cwd);
+  assertConfigFile(file);
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!config || typeof config !== 'object' || Array.isArray(config) ||
+        !config.profiles || typeof config.profiles !== 'object' || Array.isArray(config.profiles)) {
+      throw new Error('invalid configuration');
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw new Error(`工作区登录态无法解析，请在当前工作区重新登录: ${file}`);
+  }
+  const result = normalizeConfig(config);
+  configPaths.set(result, file);
+  return result;
 }
 
 function saveConfig(config) {
-  ensureUserConfigDir();
-  const normalized = normalizeConfig(config);
-  const tempFile = `${CONFIG_FILE}.${process.pid}.tmp`;
-  fs.writeFileSync(tempFile, `${JSON.stringify(normalized, null, 2)}\n`, {
-    mode: 0o600,
-  });
-  fs.renameSync(tempFile, CONFIG_FILE);
+  const file = getConfigFile(config);
+  assertConfigFile(file);
+  const directory = path.dirname(file);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  fs.chmodSync(directory, 0o700);
+  const ignore = path.join(directory, '.gitignore');
+  let current = '';
   try {
-    fs.chmodSync(CONFIG_FILE, 0o600);
-  } catch {
-    // chmod is best-effort on non-POSIX filesystems.
-  }
+    if (!fs.lstatSync(ignore).isFile() || fs.lstatSync(ignore).isSymbolicLink()) throw new Error('登录态忽略文件必须是普通文件');
+    current = fs.readFileSync(ignore, 'utf8');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const missing = ['/profiles.json', '/profiles.json.*'].filter(entry => !current.split(/\r?\n/).includes(entry));
+  if (missing.length) fs.writeFileSync(ignore, `${current}${current && !current.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`, { mode: 0o600 });
+  atomicWriteJson(file, normalizeConfig(config));
+  fs.chmodSync(file, 0o600);
+  configPaths.set(config, file);
 }
 
 function normalizeBaseUrl(value) {
@@ -441,6 +444,7 @@ module.exports = {
   GLOBAL_ENV_FILE,
   PROJECT_STATE_FILE,
   getProfile,
+  getConfigFile,
   loadGlobalEnv,
   loadConfig,
   loadProjectState,

package/lib/migration-advice.js

@@ -0,0 +1,19 @@
+// Static guidance: no registry requests, installation or workspace mutations.
+function migrationAdvice() {
+  return {
+    generation: 'v1',
+    message: '建议评估升级到 OpenXiangda 2.0；新应用优先使用 V2，现有应用先核实能力覆盖、迁移成本与验收方案。',
+    launcherInstallCommand: 'npm install -g openxiangda@latest --registry=https://registry.npmjs.org',
+    nodeRequirement: '>=24',
+    assessCommand: 'openxiangda migrate assess --to v2',
+    guide: 'https://github.com/1377385356/openxiangda/blob/master/docs/getting-started.md#upgrade',
+    workspacePolicy: '更新统一入口后旧项目仍使用 V1；不会自动转换应用、数据或流程。',
+  };
+}
+
+function printMigrationAdvice() {
+  const advice = migrationAdvice();
+  process.stderr.write(`\n${advice.message}\nNode.js 24+：${advice.launcherInstallCommand}\n使用新版全局入口在旧项目评估：${advice.assessCommand}\n${advice.workspacePolicy}\nCLI / Skill / MCP 安装升级说明：${advice.guide}\n`);
+}
+
+module.exports = { migrationAdvice, printMigrationAdvice };

package/lib/workspace-init.js

@@ -41,6 +41,7 @@ function initWorkspace(options = {}) {
     throw new Error('workspace init 绑定应用时必须同时提供 --profile 和 --app-type');
   }
 
+  const resolvedProfile = profileName ? getProfile(loadConfig(targetDir, { exact: true }), profileName) : null;
   ensureCanInitialize(targetDir, force, templateDir);
   copyTemplate(templateDir, targetDir, {
     __WORKSPACE_PACKAGE_NAME__: packageName,
@@ -49,8 +50,7 @@ function initWorkspace(options = {}) {
 
   let bound = null;
   if (profileName && appType) {
-    const config = loadConfig();
-    const resolved = getProfile(config, profileName);
+    const resolved = resolvedProfile;
     const state = {
       version: 1,
       profiles: {
@@ -125,11 +125,18 @@ function ensureCanInitialize(targetDir, force, templateDir) {
   const entries = fs
     .readdirSync(targetDir)
     .filter(name => !['.DS_Store'].includes(name));
-  if (entries.length > 0 && !force) {
+  if (entries.length > 0 && !force && !isAuthOnlyWorkspace(targetDir, entries)) {
     throw new Error(`目标目录非空: ${targetDir}。如需写入请传 --force`);
   }
 }
 
+function isAuthOnlyWorkspace(targetDir, entries) {
+  if (entries.length !== 1 || entries[0] !== '.openxiangda') return false;
+  const directory = path.join(targetDir, '.openxiangda');
+  if (!fs.lstatSync(directory).isDirectory() || fs.lstatSync(directory).isSymbolicLink()) return false;
+  return fs.readdirSync(directory).every(name => ['profiles.json', '.gitignore'].includes(name) && fs.lstatSync(path.join(directory, name)).isFile() && !fs.lstatSync(path.join(directory, name)).isSymbolicLink());
+}
+
 function normalizeRuntime(value) {
   return value === 'react-spa' || value === 'spa' ? 'react-spa' : 'legacy';
 }
@@ -154,7 +161,7 @@ function copyTemplate(sourceDir, targetDir, replacements, baseDir = sourceDir) {
 function shouldSkipTemplateEntry(baseDir, sourcePath, entryName) {
   if (TEMPLATE_IGNORE_NAMES.has(entryName)) return true;
   const relativePath = path.relative(baseDir, sourcePath).split(path.sep).join('/');
-  return TEMPLATE_IGNORE_PATHS.has(relativePath);
+  return TEMPLATE_IGNORE_PATHS.has(relativePath) || /^\.openxiangda\/(profiles\.json|session\.json)(\.|$)/.test(relativePath);
 }
 
 function applyReplacements(content, replacements) {

package/openxiangda-skills/SKILL.md

@@ -19,6 +19,10 @@ If the workspace contains `app-workspace.config.ts`, forms/pages/resource manife
 
 For an existing V1 project, proactively check whether V2 covers its required capabilities, whether it is still in testing, and whether migration cost is manageable. When those conditions hold, recommend V2 first and explain the benefit, rebuild scope and verification cost. Use the unified entry's `openxiangda migrate assess --to v2` for source pointers; confirm the project design, data/workflow mapping, acceptance and rollback before implementing migration. Keep unknown conditions explicit and continue current maintenance with the matching engine until migration is authorized.
 
+## Installation and upgrade
+
+For CLI, Skill and MCP setup or upgrades, read the [unified installation guide](https://github.com/1377385356/openxiangda/blob/master/docs/getting-started.md#upgrade). Install the global launcher with Node.js 24+ using `npm install -g openxiangda@latest --registry=https://registry.npmjs.org`. Use that global command for `migrate assess`; a project-local V1 CLI does not implement it. Workspace updates remain on `legacy-v1`. Refresh matching skills after dependency updates and restart a configured V2 MCP client to load its new project version. Never automatically replace a V1 project dependency with V2.
+
 ## 1.x Delivery V2 is the normal 1.x release path
 
 When `app-workspace.config.ts` declares `deliveryVersion: 2`, all later V1 SDD,
@@ -229,3 +233,5 @@ The lease is app-level promotion ownership, while worktree ownership prevents tw
 - `../openxiangda-open-api/SKILL.md`
 
 Load a reference only when the selected subskill explicitly requires it. Workspace `AGENTS.md` remains authoritative for project-specific constraints.
+
+平台登录态只使用当前工作区的 `.openxiangda/profiles.json`，不再读取或合并全局 profiles。升级后请进入每个项目运行 `openxiangda login <platform-url>`。登录文件自动加入 Git 忽略规则，不得提交或打包。