openxiangda 2.0.0-alpha.98 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenXiangda contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,29 @@
-# openxiangda
+# OpenXiangda 2.0
 
-`openxiangda` is the only application-facing OpenXiangda 2.0 package. Use its
-stable subpaths instead of depending on physical implementation packages:
+`openxiangda` 是应用开发统一安装的根包，提供 CLI、MCP、中文使用资料及同版本的 `openxiangda-v2` Skill。已有项目使用锁定版本；新项目使用明确的 2.0 版本。不要用未指定版本的全局命令判断项目行为。
 
-- `openxiangda/core`
-- `openxiangda/field-kit`
-- `openxiangda/react`
-- `openxiangda/nest`
-- `openxiangda/testing`
+```bash
+pnpm openxiangda context --json
+pnpm openxiangda docs
+pnpm openxiangda docs getting-started
+pnpm openxiangda skill install --workspace . --force
+pnpm openxiangda dev
+```
 
-The package also owns the `openxiangda` CLI and the version-matched
-`openxiangda-v2` AI Skill distribution. OpenXiangda 1.x remains on the 1.x
-version line and is not a compatibility target for this package.
+应用导入统一子路径：
 
-## Standard component UI
+| 子路径 | 用途 |
+| --- | --- |
+| `openxiangda/config` | 模型、任务页、权限与应用声明 |
+| `openxiangda/core` | 数据客户端与契约 |
+| `openxiangda/react` | PC 页面、管理入口与标准组件 |
+| `openxiangda/mobile` | 手机端组件 |
+| `openxiangda/field-kit` | 字段、表单与详情 |
+| `openxiangda/nest` | 按需启用的业务后端 |
+| `openxiangda/testing` | 权限与业务测试辅助 |
 
-`OpenXiangdaApplication` includes the default Ant Design component styles, Chinese
-locale and contextual message/notification support. Standalone component consumers
-can wrap their content in `OpenXiangdaUiProvider`. Custom admin pages use
-`OpenXiangdaAdminPage`; business fields use `openxiangda/field-kit`.
+默认在本地运行 React，连接远端测试平台；标准 CRUD、审批和通知无需自建后端。`check` 是统一校验入口；`deploy` 已包含校验。生产通过 `deploy --environment production --from <test-deployment-id>` 复用成功测试版本。
 
-The platform has no appearance preferences or color configuration. Keep custom
-styles scoped to their components and use the library defaults. The application
-owns document resets. Mobile pages use `openxiangda/mobile` and its scoped
-stylesheet; do not import the upstream mobile root entry's document reset.
+MCP 使用 `pnpm exec openxiangda --mcp-stdio --cwd <工作区绝对路径>`。先读取 workspace_context，再使用 docs_read 查询同版本中文正文。完整参数可运行 `pnpm openxiangda docs mcp`。
+
+`OpenXiangdaApplication` 包含默认 Ant Design 样式、中文语言和消息上下文；独立组件可使用 `OpenXiangdaUiProvider`。管理页面使用 `OpenXiangdaAdminPage`，字段使用 Field Kit。自定义样式限制在组件内，应用负责全局重置；手机端只导入本包的局部样式，不引入上游移动库的全局重置。

package/bin/distribution/commands.js

@@ -0,0 +1,55 @@
+import { bundledRelease, registryMetadata, VERSION } from './releases.js';
+import { flagValue, fail } from './workspace.js';
+import { update } from './update.js';
+import { assessMigration } from './migrate.js';
+import { installDistributionSkills } from './skills.js';
+
+export async function distributionCommand(context, args) {
+  const command = args[0];
+  const skillInstall = command === 'skill' && args[1] === 'install';
+  if (!['version', 'update', 'changelog', 'migrate'].includes(command) && !skillInstall) return false;
+  validateArguments(command, args.slice(1));
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write('openxiangda version [--json]\nopenxiangda update check|install [--target workspace|launcher] [--dry-run] [--json]\nopenxiangda changelog [version] [--json]\nopenxiangda migrate assess --to v2 [--json]\nopenxiangda skill install [--workspace <directory> | --destination <directory>] [--agent codex|claude|qoder|dual] [--force] [--dry-run]\n以上命令支持 --cwd <directory>。新应用默认 V2，项目升级保持原代际。\n');
+    return true;
+  }
+  let data;
+  if (skillInstall) data = await installDistributionSkills(context, args);
+  if (command === 'version') data = {
+    productVersion: context.manifest.version,
+    workspace: context.workspace,
+    engine: { version: context.engine.version, generation: context.engine.generation, source: context.engine.source, packageRoot: context.engine.packageRoot, declaredVersion: context.engine.declaredVersion },
+    nodeVersion: process.versions.node,
+  };
+  if (command === 'update') data = update(context, args);
+  if (command === 'migrate') data = assessMigration(context, args);
+  if (command === 'changelog') {
+    const requested = args[1] && !args[1].startsWith('-') ? args[1] : context.engine.version;
+    if (!VERSION.test(requested)) fail('DISTRIBUTION_VERSION_INVALID', requested);
+    data = bundledRelease(context.engine.packageRoot, requested);
+    if (data.available === false && requested !== context.engine.version) {
+      const manifest = registryMetadata(requested, flagValue(args, '--registry'));
+      data = manifest.openxiangdaRelease || data;
+    }
+  }
+  const result = { schemaVersion: skillInstall ? 'openxiangda.cli-result/v2' : 'openxiangda.distribution/v1', ok: true, operation: skillInstall ? 'skill install' : command, data };
+  process.stdout.write(`${args.includes('--json') ? JSON.stringify(result) : JSON.stringify(data, null, 2)}\n`);
+  return true;
+}
+
+function validateArguments(command, args) {
+  const booleans = new Set(['--json', '--help', '-h', ...(command === 'skill' ? ['--force', '--dry-run'] : command === 'update' ? ['--dry-run'] : [])]);
+  const values = new Set(['--cwd', ...({ update: ['--target', '--registry'], changelog: ['--registry'], migrate: ['--to'], skill: ['--workspace', '--destination', '--dest', '--agent'] }[command] || [])]);
+  const seen = new Set(); let positionals = 0;
+  for (let i = 0; i < args.length; i++) {
+    const argument = args[i], key = argument.split('=')[0];
+    if (!argument.startsWith('-')) { positionals++; continue; }
+    if (seen.has(key)) fail('DISTRIBUTION_ARGUMENT_INVALID', `重复参数 ${key}`);
+    seen.add(key);
+    if (booleans.has(argument)) continue;
+    if (!values.has(key)) fail('DISTRIBUTION_ARGUMENT_INVALID', argument);
+    if (argument.includes('=')) { if (!argument.slice(key.length + 1)) fail('DISTRIBUTION_ARGUMENT_REQUIRED', key); }
+    else if (!args[++i] || args[i].startsWith('-')) fail('DISTRIBUTION_ARGUMENT_REQUIRED', key);
+  }
+  if (positionals > (command === 'version' ? 0 : 1)) fail('DISTRIBUTION_ARGUMENT_INVALID', '多余的位置参数');
+}

package/bin/distribution/launcher.js

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { discoverWorkspace, flagValue, readJson, resolveEngine } from './workspace.js';
+import { distributionCommand } from './commands.js';
+
+export async function launch(packageRoot, args = process.argv.slice(2)) {
+  const manifest = readJson(join(packageRoot, 'package.json'));
+  const workspace = discoverWorkspace(flagValue(args, '--cwd') || (args[0] === 'skill' ? flagValue(args, '--workspace') : null) || process.cwd());
+  // Launcher-only updates must also work when a project's dependencies are not yet installed.
+  const launcherUpdate = args[0] === 'update' && flagValue(args, '--target') === 'launcher';
+  const engine = resolveEngine(launcherUpdate ? null : workspace, packageRoot);
+  const context = { manifest, packageRoot, workspace, engine };
+  if (await distributionCommand(context, args)) return;
+  if (!args.length || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write('统一分发命令：version、update check|install、changelog、migrate assess。\nSkill 安装支持 --workspace、--destination 和 --agent；正文跟随项目版本。\n\n');
+  }
+  const env = { ...process.env };
+  for (const key of ['OPENXIANGDA_DISTRIBUTION_NAME', 'OPENXIANGDA_DISTRIBUTION_VERSION', 'OPENXIANGDA_DOCUMENTATION_ROOT', 'OPENXIANGDA_SKILLS_ROOT']) delete env[key];
+  if (engine.generation === 'v2') {
+    env.OPENXIANGDA_DISTRIBUTION_NAME = 'openxiangda';
+    env.OPENXIANGDA_DISTRIBUTION_VERSION = engine.version;
+    env.OPENXIANGDA_DOCUMENTATION_ROOT = join(engine.packageRoot, 'documentation');
+    if (existsSync(join(engine.packageRoot, 'skills'))) env.OPENXIANGDA_SKILLS_ROOT = join(engine.packageRoot, 'skills');
+  }
+  const forwarded = engine.generation === 'v1' ? removeCwd(args) : args;
+  const child = spawn(process.execPath, [engine.entry, ...forwarded], {
+    cwd: engine.generation === 'v1' ? workspace?.root || process.cwd() : process.cwd(), env, stdio: 'inherit',
+  });
+  const signals = ['SIGINT', 'SIGTERM'];
+  const handlers = signals.map(signal => () => child.kill(signal));
+  signals.forEach((signal, i) => process.on(signal, handlers[i]));
+  try {
+    const { code, signal } = await new Promise((resolve, reject) => {
+      child.once('error', reject);
+      child.once('exit', (code, signal) => resolve({ code, signal }));
+    });
+    process.exitCode = code ?? (signal === 'SIGINT' ? 130 : 143);
+  } finally { signals.forEach((signal, i) => process.removeListener(signal, handlers[i])); }
+}
+
+function removeCwd(args) {
+  const output = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--cwd') i++;
+    else if (!args[i].startsWith('--cwd=')) output.push(args[i]);
+  }
+  return output;
+}

package/bin/distribution/migrate.js

@@ -0,0 +1,60 @@
+import { readdirSync, lstatSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fail, flagValue } from './workspace.js';
+
+export function assessMigration(context, args) {
+  if (args[1] !== 'assess' || flagValue(args, '--to') !== 'v2') fail('DISTRIBUTION_MIGRATION_ARGUMENT_INVALID', '用法：openxiangda migrate assess --to v2');
+  if (context.workspace?.generation !== 'v1') fail('DISTRIBUTION_MIGRATION_V1_REQUIRED', '请在 V1 工作区内进行迁移评估');
+  const root = context.workspace.root;
+  const inventory = { resources: [], workflows: [], permissions: [], pages: [], runtime: [], data: [] };
+  let files = 0, bytes = 0, entries = 0;
+  const skipped = [];
+  const excluded = new Set(['node_modules', '.git', '.codegraph', 'dist', 'build', 'coverage', '.openxiangda', '.agents', '.codex', '.claude', '.qoder', '.cursor', '.env', 'secrets', 'logs']);
+  function visit(directory, depth = 0) {
+    if (depth > 12) { skipped.push(relative(root, directory)); return; }
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (++entries > 20000) fail('DISTRIBUTION_MIGRATION_SCAN_LIMIT', '目录超过 20000 个条目；请按应用拆分评估范围');
+      if (excluded.has(entry.name) || entry.name.startsWith('.env')) continue;
+      const file = join(directory, entry.name), path = relative(root, file);
+      if (entry.isSymbolicLink()) { skipped.push(path); continue; }
+      if (entry.isDirectory()) { visit(file, depth + 1); continue; }
+      if (!/\.(?:[cm]?[jt]sx?|json|ya?ml|sql)$/.test(entry.name) || /lock\.json$/.test(entry.name)) continue;
+      const size = lstatSync(file).size;
+      if (++files > 5000 || bytes + size > 20 * 1024 * 1024) fail('DISTRIBUTION_MIGRATION_SCAN_LIMIT', '工作区超过 5000 个文件或 20 MiB；请按应用拆分评估范围');
+      if (size > 1024 * 1024) { skipped.push(path); continue; }
+      bytes += size;
+      const text = readFileSync(file, 'utf8');
+      // Return source pointers, never credentials, customer records or executable config values.
+      if (/resource|form/i.test(path) || /defineResource|formUuid/.test(text)) inventory.resources.push(path);
+      if (/workflow|process|automation/i.test(path) || /JS_CODE|approver/.test(text)) inventory.workflows.push(path);
+      if (/permission|authz|role/i.test(path) || /permissionGroup|permissionCode/.test(text)) inventory.permissions.push(path);
+      if (/page|route|\.tsx$|\.jsx$/i.test(path)) inventory.pages.push(path);
+      if (/function|server|runtime|backend/i.test(path)) inventory.runtime.push(path);
+      if (/migration|schema|\.sql$/i.test(path)) inventory.data.push(path);
+    }
+  }
+  visit(root);
+  return {
+    schemaVersion: 'openxiangda.migration-assessment/v1', from: 'v1', to: 'v2', root, readOnly: true,
+    engineVersion: context.engine.version, scanned: { files, bytes }, complete: skipped.length === 0, skipped, inventory,
+    recommendation: {
+      preferredGeneration: 'v2',
+      policy: 'V2 能力满足、项目仍在测试阶段且迁移成本可控时，优先建议采用 V2。',
+      decision: '条件待确认；本地源码指针不能证明能力覆盖、上线阶段或迁移成本。',
+      criteria: [
+        { code: 'capability-fit', status: 'needs-confirmation', question: 'V2 是否覆盖项目需要的模型、页面、权限、流程与外部集成？' },
+        { code: 'project-stage', status: 'needs-confirmation', question: '项目是否仍在测试阶段，已有多少真实数据和在途流程？' },
+        { code: 'migration-cost', status: 'needs-confirmation', question: '重建、数据映射、测试和切换的成本是否可控？' },
+      ],
+    },
+    assessment: [
+      { area: 'resources', pointers: inventory.resources.length, decision: '逐项确认业务模型、字段、关联和服务端约束，再映射到 V2 Data API；V1 表单标识不直接作为 V2 模型。' },
+      { area: 'workflows', pointers: inventory.workflows.length, decision: '核对节点、审批人规则、JS_CODE 副作用、通知和在途实例；在途流程须制定独立切换方案。' },
+      { area: 'permissions', pointers: inventory.permissions.length, decision: '由项目确认角色并集、数据范围和字段权限，按真实角色回归；不可直接复制旧权限组。' },
+      { area: 'data', pointers: inventory.data.length, decision: '此次只检查本地源码。远端数据量、附件、主键映射和历史流程尚未读取，需另行授权盘点、校验和回滚演练。' },
+      { area: 'experience', pointers: inventory.pages.length, decision: '先确认 AppSpec 产品、页面和权限设计基线，再逐页重建并验收 PC/移动端。' },
+    ],
+    nextSteps: ['确认范围与源环境', '完成详细设计和迁移映射', '在测试环境演练并核对数量、摘要和权限', '冻结切换窗口与回滚条件', '逐项目审批实施'],
+    migrated: false,
+  };
+}

package/bin/distribution/releases.js

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fail, readJson } from './workspace.js';
+
+export const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+export const RELEASE_REPOSITORY = 'https://github.com/1377385356/openxiangda';
+export const GENERATION_CHANNEL = { v1: 'legacy-v1', v2: 'stable-v2' };
+
+export function bundledRelease(packageRoot, version) {
+  const file = join(packageRoot, 'releases', `${version}.json`);
+  if (existsSync(file)) return readJson(file);
+  const manifest = readJson(join(packageRoot, 'package.json'));
+  return (manifest.openxiangdaRelease?.version === version ? manifest.openxiangdaRelease : null) || {
+    version, available: false, url: `${RELEASE_REPOSITORY}/releases/tag/v${version}`,
+    summary: '此历史版本未随包提供结构化更新说明。',
+  };
+}
+
+export function registryMetadata(selector, registry = 'https://registry.npmjs.org') {
+  selector = GENERATION_CHANNEL[selector] || selector;
+  if (!VERSION.test(selector) && !['legacy-v1', 'stable-v2', 'latest', 'alpha'].includes(selector)) fail('DISTRIBUTION_VERSION_INVALID', selector);
+  const url = new URL(registry);
+  if (url.username || url.password || url.protocol !== 'https:' && !['127.0.0.1', 'localhost'].includes(url.hostname)) fail('DISTRIBUTION_REGISTRY_INVALID', 'registry 必须为 HTTPS 地址');
+  const result = spawnSync('npm', ['view', `openxiangda@${selector}`, '--json', `--registry=${url.href}`], {
+    encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024,
+    env: { ...process.env, npm_config_fetch_retries: '0', npm_config_fetch_timeout: '20000' },
+  });
+  if (result.error || result.status !== 0) fail('DISTRIBUTION_REGISTRY_UNAVAILABLE', '无法读取版本资料；本地命令与随包说明仍可使用');
+  let manifest;
+  try { manifest = JSON.parse(result.stdout); } catch { fail('DISTRIBUTION_REGISTRY_RESPONSE_INVALID', 'npm 未返回有效 JSON'); }
+  if (!VERSION.test(manifest.version || '') || manifest.name !== 'openxiangda') fail('DISTRIBUTION_REGISTRY_RESPONSE_INVALID', 'npm 返回了不匹配的包');
+  return manifest;
+}
+
+export function compareVersions(left, right) {
+  const parse = version => { const [base, ...pre] = version.split('-'); return { base: base.split('.').map(Number), pre: pre.join('-') }; };
+  const a = parse(left), b = parse(right);
+  for (let i = 0; i < 3; i++) if (a.base[i] !== b.base[i]) return Math.sign(a.base[i] - b.base[i]);
+  if (a.pre === b.pre) return 0;
+  if (!a.pre || !b.pre) return a.pre ? -1 : 1;
+  const ap = a.pre.split('.'), bp = b.pre.split('.');
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    if (ap[i] === bp[i]) continue;
+    if (ap[i] === undefined || bp[i] === undefined) return ap[i] === undefined ? -1 : 1;
+    const an = /^\d+$/.test(ap[i]), bn = /^\d+$/.test(bp[i]);
+    if (an && bn) return Math.sign(Number(ap[i]) - Number(bp[i]));
+    if (an !== bn) return an ? -1 : 1;
+    return ap[i] < bp[i] ? -1 : 1;
+  }
+  return 0;
+}

package/bin/distribution/skills.js

@@ -0,0 +1,80 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { fail, flagValue, readJson } from './workspace.js';
+
+export async function installDistributionSkills(context, args) {
+  const workspace = flagValue(args, '--workspace');
+  const destination = flagValue(args, '--destination') || flagValue(args, '--dest');
+  const agent = flagValue(args, '--agent') || 'codex';
+  if (!['codex', 'claude', 'qoder', 'dual'].includes(agent)) fail('DISTRIBUTION_SKILL_AGENT_INVALID', agent);
+  const homes = { codex: process.env.CODEX_HOME || join(homedir(), '.codex'), claude: process.env.CLAUDE_HOME || join(homedir(), '.claude'), qoder: process.env.QODER_HOME || join(homedir(), '.qoder') };
+  const destinations = destination ? [resolve(destination)] : workspace ? [resolve(workspace, '.agents/skills')] : (agent === 'dual' ? Object.values(homes) : [homes[agent]]).map(path => join(path, 'skills'));
+  const staging = mkdtempSync(join(tmpdir(), 'openxiangda-skills-'));
+  const source = join(staging, 'skills');
+  try {
+    const guidanceTemplate = workspace && context.engine.generation === 'v2' && !args.includes('--dry-run')
+      ? readFileSync(join(context.engine.packageRoot, 'documentation/AGENTS.md'), 'utf8') : undefined;
+    if (context.engine.generation === 'v1') {
+      const require = createRequire(join(context.engine.packageRoot, 'package.json'));
+      const { installSkills } = require(join(context.engine.packageRoot, 'lib/skills.js'));
+      installSkills({ agent: 'codex', dest: source, env: { ...process.env, CODEX_HOME: staging } });
+      // Historical V1 packages named their root skill openxiangda. Preserve its content under V1 ownership.
+      if (existsSync(join(source, 'openxiangda'))) {
+        renameSync(join(source, 'openxiangda'), join(source, 'openxiangda-v1'));
+        const file = join(source, 'openxiangda-v1/SKILL.md');
+        writeFileSync(file, readFileSync(file, 'utf8').replace(/^name: openxiangda$/m, 'name: openxiangda-v1'));
+      }
+    } else {
+      const { installSkills } = await importEngineModule(context.engine.packageRoot, 'openxiangda-skill-kit');
+      await installSkills({ skillsRoot: join(context.engine.packageRoot, 'skills'), destination: source });
+    }
+    const router = join(source, 'openxiangda');
+    cpSync(join(context.packageRoot, 'launcher-skill/openxiangda'), router, { recursive: true });
+    const file = join(router, 'SKILL.md');
+    writeFileSync(file, readFileSync(file, 'utf8').replaceAll('__OPENXIANGDA_VERSION__', context.manifest.version));
+    const names = readdirSync(source, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name).sort();
+    for (const dest of destinations) for (const name of names) {
+      if (existsSync(join(dest, name)) && !args.includes('--force')) fail('SKILL_ALREADY_EXISTS', `${join(dest, name)}；使用 --force 显式替换`);
+    }
+    if (!args.includes('--dry-run')) for (const dest of destinations) installSet(source, dest, names);
+    let guidance;
+    if (workspace && context.engine.generation === 'v2' && !args.includes('--dry-run')) {
+      const { refreshWorkspaceGuidance } = await importEngineModule(context.engine.packageRoot, 'openxiangda-skill-kit');
+      guidance = refreshWorkspaceGuidance(resolve(workspace), guidanceTemplate);
+    }
+    return { destinations, installed: names, engineVersion: context.engine.version, generation: context.engine.generation, dryRun: args.includes('--dry-run'), ...(guidance ? { guidance } : {}) };
+  } finally { rmSync(staging, { recursive: true, force: true }); }
+}
+
+function importEngineModule(packageRoot, name) {
+  const require = createRequire(join(packageRoot, 'package.json'));
+  // These ESM packages do not expose package.json to require.resolve.
+  // Resolve from this engine's dependency paths, never the launcher's imports.
+  const file = require.resolve.paths(name).map(base => join(base, name, 'package.json')).find(existsSync);
+  if (!file) fail('DISTRIBUTION_ENGINE_MODULE_MISSING', name);
+  const manifest = readJson(file);
+  const entry = manifest.exports?.['.']?.import || manifest.main;
+  if (manifest.name !== name || typeof entry !== 'string' || !entry.startsWith('./') || !resolve(dirname(file), entry).startsWith(`${dirname(file)}/`)) fail('DISTRIBUTION_ENGINE_MODULE_INVALID', name);
+  return import(pathToFileURL(resolve(dirname(file), entry)).href);
+}
+
+function installSet(source, destination, names) {
+  mkdirSync(destination, { recursive: true });
+  const transaction = mkdtempSync(join(destination, '.openxiangda-distribution-'));
+  const installed = [], backups = [];
+  try {
+    for (const name of names) cpSync(join(source, name), join(transaction, 'next', name), { recursive: true });
+    for (const name of names) {
+      const target = join(destination, name), backup = join(transaction, 'previous', name);
+      if (existsSync(target)) { mkdirSync(dirname(backup), { recursive: true }); renameSync(target, backup); backups.push({ target, backup }); }
+      renameSync(join(transaction, 'next', name), target); installed.push(target);
+    }
+  } catch (error) {
+    for (const target of installed.reverse()) rmSync(target, { recursive: true, force: true });
+    for (const { target, backup } of backups.reverse()) renameSync(backup, target);
+    throw error;
+  } finally { rmSync(transaction, { recursive: true, force: true }); }
+}

package/bin/distribution/update.js

@@ -0,0 +1,68 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { bundledRelease, compareVersions, registryMetadata, VERSION, GENERATION_CHANNEL } from './releases.js';
+import { fail, flagValue, readJson } from './workspace.js';
+
+export function updatePlan(context, args, metadata) {
+  const target = flagValue(args, '--target') || (context.workspace ? 'workspace' : 'launcher');
+  if (!['workspace', 'launcher'].includes(target)) fail('DISTRIBUTION_UPDATE_TARGET_INVALID', target);
+  if (target === 'workspace' && !context.workspace) fail('DISTRIBUTION_WORKSPACE_REQUIRED', '请在项目中执行 workspace 升级');
+  const generation = target === 'launcher' ? 'v2' : context.workspace.generation;
+  if (!VERSION.test(metadata.version) || !metadata.version.startsWith(generation === 'v1' ? '1.' : '2.') || metadata.version.includes('-')) {
+    fail('DISTRIBUTION_UPDATE_GENERATION_MISMATCH', `${generation} 稳定渠道返回了 ${metadata.version}`);
+  }
+  const currentVersion = target === 'launcher' ? context.manifest.version : context.engine.version;
+  const plan = {
+    target, generation, channel: GENERATION_CHANNEL[generation], currentVersion, version: metadata.version,
+    updateAvailable: compareVersions(metadata.version, currentVersion) > 0,
+    compatibility: metadata.engines || {}, release: metadata.openxiangdaRelease || { version: metadata.version, available: false },
+    cwd: target === 'workspace' ? context.workspace.root : process.cwd(),
+    command: 'npm', args: ['install', '--global', `openxiangda@${metadata.version}`],
+  };
+  if (target === 'workspace') {
+    const manifestFile = join(context.workspace.root, 'package.json');
+    if (!existsSync(manifestFile)) fail('DISTRIBUTION_PACKAGE_MANIFEST_REQUIRED', '项目缺少 package.json，不能自动决定依赖归属');
+    const manifest = readJson(manifestFile);
+    const locks = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'].filter(file => existsSync(join(context.workspace.root, file)));
+    if (locks.length > 1) fail('DISTRIBUTION_PACKAGE_MANAGER_CONFLICT', locks.join(', '));
+    const manager = manifest.packageManager?.split('@')[0] || ({ 'pnpm-lock.yaml': 'pnpm', 'package-lock.json': 'npm', 'yarn.lock': 'yarn' }[locks[0]]) || 'npm';
+    if (!['npm', 'pnpm', 'yarn'].includes(manager)) fail('DISTRIBUTION_PACKAGE_MANAGER_UNSUPPORTED', manager);
+    const dependency = manifest.dependencies?.openxiangda;
+    const spec = `openxiangda@${metadata.version}`;
+    plan.command = manager;
+    plan.args = manager === 'npm' ? ['install', dependency ? '--save-prod' : '--save-dev', '--save-exact', spec]
+      : ['add', ...(dependency ? [] : ['--dev']), '--exact', spec, ...(manager === 'pnpm' && existsSync(join(context.workspace.root, 'pnpm-workspace.yaml')) ? ['--workspace-root'] : [])];
+    if (manager === 'pnpm' && existsSync(join(context.workspace.root, 'pnpm-workspace.yaml'))) {
+      plan.args = ['--recursive', '--include-workspace-root', 'update', '--save-exact', spec];
+    }
+  }
+  const registry = flagValue(args, '--registry') || 'https://registry.npmjs.org';
+  plan.args.push(`--registry=${registry}`);
+  return plan;
+}
+
+export function update(context, args) {
+  const action = args[1] && !args[1].startsWith('-') ? args[1] : 'check';
+  if (!['check', 'install'].includes(action)) fail('DISTRIBUTION_UPDATE_ACTION_INVALID', action);
+  const target = flagValue(args, '--target') || (context.workspace ? 'workspace' : 'launcher');
+  if (!['workspace', 'launcher'].includes(target)) fail('DISTRIBUTION_UPDATE_TARGET_INVALID', target);
+  if (target === 'workspace' && !context.workspace) fail('DISTRIBUTION_WORKSPACE_REQUIRED', '请在项目中执行 workspace 升级');
+  const channel = GENERATION_CHANNEL[target === 'launcher' ? 'v2' : context.workspace?.generation || 'v2'];
+  let metadata;
+  try { metadata = registryMetadata(channel, flagValue(args, '--registry')); }
+  catch (error) {
+    if (action === 'install') throw error;
+    return { status: 'offline', target, channel, error: { code: error.code, message: error.message }, release: bundledRelease(context.engine.packageRoot, context.engine.version) };
+  }
+  const plan = updatePlan(context, args, metadata);
+  if (action === 'check' || args.includes('--dry-run')) return { status: 'checked', ...plan, executed: false };
+  if (!plan.updateAvailable) return { status: 'current', ...plan, executed: false };
+  const requirement = metadata.engines?.node;
+  // Published stable distributions use a lower-bound Node contract; reject unknown expressions instead of guessing.
+  if (requirement && !/^>=\d+(?:\.\d+){0,2}$/.test(requirement)) fail('DISTRIBUTION_NODE_REQUIREMENT_UNSUPPORTED', requirement);
+  if (requirement && compareVersions(process.versions.node, requirement.slice(2).split('.').concat(['0', '0']).slice(0, 3).join('.')) < 0) fail('DISTRIBUTION_NODE_VERSION_REQUIRED', `目标版本需要 Node.js ${requirement}`);
+  const result = spawnSync(plan.command, plan.args, { cwd: plan.cwd, stdio: args.includes('--json') ? ['inherit', 'pipe', 'pipe'] : 'inherit', timeout: 600000, maxBuffer: 8 * 1024 * 1024 });
+  if (result.error || result.status !== 0) fail('DISTRIBUTION_UPDATE_INSTALL_FAILED', '包管理器未完成升级；保留项目与锁文件现场，请检查后使用原计划恢复');
+  return { status: 'installed', ...plan, executed: true, next: plan.target === 'workspace' ? '按项目说明执行 check 和业务验收；需要刷新 Skill 时显式运行 skill install。' : '重新运行 openxiangda version --json 核对入口和项目引擎。' };
+}

package/bin/distribution/workspace.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+
+export function fail(code, message) {
+  throw Object.assign(new Error(`${code}: ${message}`), { code });
+}
+
+export function readJson(file) {
+  if (statSync(file).size > 2 * 1024 * 1024) fail('DISTRIBUTION_FILE_TOO_LARGE', file);
+  try { return JSON.parse(readFileSync(file, 'utf8')); }
+  catch { fail('DISTRIBUTION_JSON_INVALID', file); }
+}
+
+export function flagValue(args, name) {
+  const values = [];
+  for (let i = 0; i < args.length && args[i] !== '--'; i++) {
+    if (args[i] === name) {
+      if (!args[i + 1] || args[i + 1].startsWith('--')) fail('DISTRIBUTION_ARGUMENT_REQUIRED', name);
+      values.push(args[++i]);
+    } else if (args[i].startsWith(`${name}=`)) values.push(args[i].slice(name.length + 1));
+  }
+  if (values.length > 1 || values.some(value => !value)) fail('DISTRIBUTION_ARGUMENT_INVALID', name);
+  return values[0];
+}
+
+// Discovery reads markers only. Loading either generation's executable config belongs to its engine.
+export function discoverWorkspace(cwd) {
+  let root = realpathSync(resolve(cwd));
+  if (!statSync(root).isDirectory()) fail('WORKSPACE_DIRECTORY_REQUIRED', root);
+  while (true) {
+    const v2 = ['openxiangda.config.ts', 'openxiangda-app.config.ts'].filter(file => existsSync(join(root, file)));
+    const v1 = ['app-workspace.config.ts'].filter(file => existsSync(join(root, file)));
+    const binding = join(root, '.openxiangda/state.json');
+    if (existsSync(binding)) {
+      const state = readJson(binding);
+      if (state.version === 1 && state.profiles && typeof state.profiles === 'object') v1.push('.openxiangda/state.json');
+    }
+    if (v1.length && v2.length || v2.length > 1) fail('WORKSPACE_GENERATION_CONFLICT', `${root} 同时存在冲突的工作区标记：${[...v1, ...v2].join(', ')}`);
+    if (v1.length || v2.length) return { root, generation: v1.length ? 'v1' : 'v2', markers: [...v1, ...v2] };
+    const parent = dirname(root);
+    if (parent === root) return null;
+    root = parent;
+  }
+}
+
+export function packageEngine(packageRoot, generation, source, declaredVersion = null) {
+  const manifest = readJson(join(packageRoot, 'package.json'));
+  const major = generation === 'v1' ? '1' : '2';
+  if (manifest.name !== 'openxiangda' || !manifest.version?.startsWith(`${major}.`)) {
+    fail('WORKSPACE_ENGINE_GENERATION_MISMATCH', `${packageRoot} 需要 ${generation} openxiangda`);
+  }
+  if (/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(declaredVersion || '') && manifest.version !== declaredVersion) {
+    fail('WORKSPACE_ENGINE_PIN_MISMATCH', `项目声明 ${declaredVersion}，已安装 ${manifest.version}；请先按锁文件安装依赖`);
+  }
+  let entry;
+  if (generation === 'v1') {
+    const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.openxiangda;
+    if (!bin) fail('WORKSPACE_ENGINE_BIN_MISSING', packageRoot);
+    entry = resolve(packageRoot, bin);
+    if (!entry.startsWith(`${realpathSync(packageRoot)}/`) && !entry.startsWith(`${resolve(packageRoot)}/`)) fail('WORKSPACE_ENGINE_BIN_INVALID', entry);
+  } else {
+    try { entry = createRequire(join(packageRoot, 'package.json')).resolve('openxiangda-cli/run'); }
+    catch { fail('WORKSPACE_ENGINE_DEPENDENCY_MISSING', `${packageRoot}: openxiangda-cli`); }
+  }
+  if (!existsSync(entry)) fail('WORKSPACE_ENGINE_BIN_MISSING', entry);
+  return { generation, version: manifest.version, source, packageRoot: realpathSync(packageRoot), entry, declaredVersion };
+}
+
+export function resolveEngine(workspace, launcherRoot) {
+  const generation = workspace?.generation || 'v2';
+  if (workspace) {
+    const manifestFile = join(workspace.root, 'package.json');
+    const manifest = existsSync(manifestFile) ? readJson(manifestFile) : {};
+    const declaredVersion = manifest.dependencies?.openxiangda || manifest.devDependencies?.openxiangda;
+    const installed = join(workspace.root, 'node_modules/openxiangda');
+    if (existsSync(join(installed, 'package.json'))) return packageEngine(installed, generation, 'workspace', declaredVersion);
+    if (declaredVersion) fail('WORKSPACE_ENGINE_NOT_INSTALLED', `${workspace.root} 已声明 openxiangda；请先按项目锁文件安装依赖`);
+  }
+  if (generation === 'v2') return packageEngine(launcherRoot, 'v2', 'launcher');
+  let legacyManifest;
+  try { legacyManifest = createRequire(join(launcherRoot, 'package.json')).resolve('openxiangda-legacy/package.json'); }
+  catch { fail('DISTRIBUTION_LEGACY_ENGINE_MISSING', '请重新安装完整的统一入口'); }
+  return packageEngine(dirname(legacyManifest), 'v1', 'bundled-v1');
+}

package/bin/run.js

@@ -1,16 +1,14 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { launch } from './distribution/launcher.js';
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const packageManifest = JSON.parse(
-  readFileSync(join(packageRoot, 'package.json'), 'utf8')
-);
-process.env.OPENXIANGDA_DISTRIBUTION_NAME = packageManifest.name;
-process.env.OPENXIANGDA_DISTRIBUTION_VERSION = packageManifest.version;
-const packagedSkills = join(packageRoot, 'skills');
-if (existsSync(packagedSkills)) {
-  process.env.OPENXIANGDA_SKILLS_ROOT ||= packagedSkills;
+try {
+  if (Number(process.versions.node.split('.')[0]) < 24) throw Object.assign(new Error('统一入口需要 Node.js 24 或更高版本；已有 V1 项目仍可使用其原工具链。'), { code: 'DISTRIBUTION_NODE_VERSION_REQUIRED' });
+  await launch(packageRoot);
+} catch (error) {
+  const result = { schemaVersion: 'openxiangda.distribution/v1', ok: false, error: { code: error.code || 'DISTRIBUTION_COMMAND_FAILED', message: error.message } };
+  (process.argv.includes('--json') ? process.stdout : process.stderr).write(`${process.argv.includes('--json') ? JSON.stringify(result) : error.message}\n`);
+  process.exitCode = 1;
 }
-await import('openxiangda-cli/run');

package/dist/browser/AuthoritativeSelector.d.ts

@@ -1,4 +1,4 @@
-import type { DepartmentReferenceValue, ResourceReferenceValue, UserReferenceValue } from 'openxiangda-contracts/browser';
+import type { DataFieldSourceLaunchBinding, DepartmentReferenceValue, ResourceReferenceValue, UserReferenceValue } from 'openxiangda-contracts/browser';
 import { type DirectoryKind } from './platform-client';
 type Source = DirectoryKind | 'resource';
 type StoredValue = UserReferenceValue | DepartmentReferenceValue | ResourceReferenceValue;
@@ -15,8 +15,9 @@ export type AuthoritativeSelectorProps = {
     resourceCode?: string;
     fieldCode?: string;
     bindings?: Record<string, unknown>;
+    launch?: DataFieldSourceLaunchBinding;
 };
-export declare function AuthoritativeSelector({ value, onChange, source, operation, multiple, disabled, id, placeholder, resourceCode, fieldCode, bindings, }: AuthoritativeSelectorProps): import("react/jsx-runtime").JSX.Element;
+export declare function AuthoritativeSelector({ value, onChange, source, operation, multiple, disabled, id, placeholder, resourceCode, fieldCode, bindings, launch: launchInput, }: AuthoritativeSelectorProps): import("react/jsx-runtime").JSX.Element;
 /** Mobile fields consume the same authoritative query and stored snapshots. */
 export declare function MobileAuthoritativeSelector(props: AuthoritativeSelectorProps): import("react/jsx-runtime").JSX.Element;
 export declare function ResolvedValueText({ source, value, }: {

package/dist/browser/AuthoritativeSelector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthoritativeSelector.d.ts","sourceRoot":"","sources":["../../src/browser/AuthoritativeSelector.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,wBAAwB,EAExB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAG3B,KAAK,MAAM,GAAG,aAAa,GAAG,UAAU,CAAC;AAWzC,KAAK,WAAW,GACZ,kBAAkB,GAClB,wBAAwB,GACxB,sBAAsB,CAAC;AAyH3B,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE,GAAG,SAAS,KAAK,IAAI,CAAC;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,QAAQ,EACR,MAAM,EACN,SAAS,EACT,QAAgB,EAChB,QAAgB,EAChB,EAAE,EACF,WAAW,EACX,YAAY,EACZ,SAAS,EACT,QAAQ,GACT,EAAE,0BAA0B,2CA8M5B;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,0BAA0B,2CAM5E;AAgCD,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,KAAK,GACN,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;CACrC,2CA2BA;AAED,gGAAgG;AAChG,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,EAAE,GACH,EAAE;IACD,MAAM,EAAE,aAAa,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;CACZ,2CAoBA"}
+{"version":3,"file":"AuthoritativeSelector.d.ts","sourceRoot":"","sources":["../../src/browser/AuthoritativeSelector.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,4BAA4B,EAC5B,wBAAwB,EAExB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAG3B,KAAK,MAAM,GAAG,aAAa,GAAG,UAAU,CAAC;AAWzC,KAAK,WAAW,GACZ,kBAAkB,GAClB,wBAAwB,GACxB,sBAAsB,CAAC;AAwI3B,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE,GAAG,SAAS,KAAK,IAAI,CAAC;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,4BAA4B,CAAC;CACvC,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,QAAQ,EACR,MAAM,EACN,SAAS,EACT,QAAgB,EAChB,QAAgB,EAChB,EAAE,EACF,WAAW,EACX,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,MAAM,EAAE,WAAW,GACpB,EAAE,0BAA0B,2CA+M5B;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,0BAA0B,2CAM5E;AAiCD,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,KAAK,GACN,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;CACrC,2CA2BA;AAED,gGAAgG;AAChG,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,EAAE,GACH,EAAE;IACD,MAAM,EAAE,aAAa,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;CACZ,2CAoBA"}