openxiangda 1.0.22 → 1.0.25

package/README.md

@@ -7,21 +7,20 @@ It uses normal platform user login tokens through `/openxiangda-api/v1`; it does
 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://yida.wisejob.cn/` to the CLI is supported; OpenXiangda stores the API base as `https://yida.wisejob.cn/service`.
 
 ```bash
-npm install -g .
-# or during local development:
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+openxiangda update check
+openxiangda skill install
+
+# during local development:
 npm link
 
-openxiangda skill install
 openxiangda skill status
-openxiangda workspace init ./my-app-workspace
-cd ./my-app-workspace
-pnpm install
 openxiangda platform add dev https://dev-lowcode.example.com
 openxiangda login --profile dev
 openxiangda env
-openxiangda app list --profile dev
-openxiangda workspace bind --profile dev --app-type APP_XXXX
-cd /path/to/sy-lowcode-app-workspace
+openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
+cd ./my-app-workspace
+pnpm install
 openxiangda workspace publish --profile dev
 openxiangda menu list --profile dev
 openxiangda workflow list --profile dev
@@ -37,6 +36,16 @@ openxiangda app snapshot APP_XXXX --profile dev --json
 
 User tokens are stored in `~/.openxiangda/profiles.json` with `0600` permissions. Project state is stored in `.openxiangda/state.json` and contains only profile-specific resource IDs.
 
+Use the official npm registry for OpenXiangda updates:
+
+```bash
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+openxiangda update check --json
+openxiangda update install
+```
+
+Domestic npm mirrors may lag and return an older OpenXiangda version. `openxiangda update check --json` is designed for AI agents: it returns the installed version, latest official npm version, whether an update is available, and the compatibility commands to run after updating. `openxiangda update install` installs from the official registry and refreshes OpenXiangda skills by default.
+
 Codex skills are installed separately from login/profile state. Run `openxiangda skill install` after installing or linking the CLI. It installs the `openxiangda` root skill plus the 7 top-level subskills into `${CODEX_HOME:-~/.codex}/skills` by default:
 
 - `openxiangda`
@@ -50,10 +59,19 @@ Codex skills are installed separately from login/profile state. Run `openxiangda
 
 Use `openxiangda skill install --dest <skills-dir>` to target a different Codex skills directory. If a same-name skill exists but was not installed by OpenXiangda, the command refuses to overwrite it unless `--force` is provided. Restart Codex after installing skills.
 
-Create a new publishable app workspace with `openxiangda workspace init <dir>`. The command writes a minimal `sy-lowcode-app-workspace` template with React, Ant Design, the single `openxiangda` package, and the required `publish:all` / `openxiangda:publish` scripts. Use `--install` to run `pnpm install` immediately, or run it manually after creation. You can also bind during initialization:
+Create a new publishable app workspace with `openxiangda workspace init <dir>`. The command writes a minimal `sy-lowcode-app-workspace` template with React, Ant Design, the single `openxiangda` package, and the required `publish:all` / `openxiangda:publish` scripts. Use `--install` to run `pnpm install` immediately, or run it manually after creation.
+
+Local workspace state is authoritative. If the current folder has no `.openxiangda/state.json` app binding, create a new app instead of searching the platform for a similar app name:
+
+```bash
+openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
+```
+
+Bind to an existing app only when the user explicitly provides an `appType` or asks to reuse an existing platform app:
 
 ```bash
 openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+openxiangda workspace bind --profile dev --app-type APP_XXXX
 ```
 
 表单页、流程表单页和自定义代码页都应在 `sy-lowcode-app-workspace` 中实现，由 `openxiangda workspace publish --profile <name>` 统一构建、上传 OSS 并注册到平台。`openxiangda form create`、`form publish`、`page publish` 只作为底层修复/诊断命令，不作为 AI 生成页面的主入口。

package/lib/cli.js

@@ -14,7 +14,7 @@ const {
 } = require('./config');
 const { requestJson } = require('./http');
 const { getSkillStatusReport, installSkills } = require('./skills');
-const { initWorkspace } = require('./workspace-init');
+const { assertCanInitializeWorkspace, initWorkspace } = require('./workspace-init');
 const {
   fail,
   openBrowser,
@@ -24,6 +24,10 @@ const {
   warn,
   writeJson,
 } = require('./utils');
+const { version: CURRENT_VERSION } = require('../package.json');
+
+const NPM_PACKAGE_NAME = 'openxiangda';
+const OFFICIAL_NPM_REGISTRY = 'https://registry.npmjs.org';
 
 async function main(argv) {
   const [command, ...rest] = argv;
@@ -33,6 +37,7 @@ async function main(argv) {
   }
 
   if (command === 'login') return login(rest);
+  if (command === 'update') return update(rest);
   if (command === 'env') return env(rest);
   if (command === 'auth') return auth(rest);
   if (command === 'platform') return platform(rest);
@@ -58,14 +63,16 @@ function printHelp() {
 
 Usage:
   openxiangda login <platform-url> [--profile name]
+  openxiangda update check|install [--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 env [--profile name]
   openxiangda workspace init [dir] [--name package-name] [--install] [--profile name --app-type APP_XXX]
+  openxiangda workspace init [dir] --profile <name> --app-name <app-name> [--install]
   openxiangda workspace bind --profile <name> --app-type <APP_XXX>
-  openxiangda workspace publish --profile <name> [--prune]
+  openxiangda workspace publish --profile <name> [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources] [--prune]
   openxiangda app list [--profile name] [--json]
   openxiangda app create <name> [--profile name] [--description text]
   openxiangda app snapshot <APP_XXX> [--profile name] [--json]
@@ -102,6 +109,199 @@ OpenXiangda 使用普通用户登录 token，不需要 AK/SK。
 JS_CODE V2 使用 trusted_node；AI 源码必须写在 src/js-code-nodes/<scriptCode>/index.ts，definition-json 中的 sourceFile.localPath 会在 validate/create 时先 TS 校验、再构建并上传为快照。`);
 }
 
+async function update(args) {
+  const requestedSubcommand = args[0] && !args[0].startsWith('--') ? args[0] : 'check';
+  const parsedArgs = requestedSubcommand === args[0] ? args.slice(1) : args;
+  const { flags } = parseArgs(parsedArgs);
+  const registry = normalizeNpmRegistry(flags.registry || OFFICIAL_NPM_REGISTRY);
+
+  if (requestedSubcommand === 'check') {
+    const result = checkOpenXiangdaUpdate(registry);
+    if (flags.json) return writeJson(result);
+    printUpdateCheck(result);
+    return;
+  }
+
+  if (requestedSubcommand === 'install') {
+    const result = installOpenXiangdaUpdate(registry, {
+      json: Boolean(flags.json),
+      skipSkills: Boolean(flags['no-skills']),
+    });
+    if (flags.json) return writeJson(result);
+    print('OpenXiangda 已更新。');
+    if (result.skillInstall?.attempted && result.skillInstall.status !== 0) {
+      warn(`skill install 未完成: ${result.skillInstall.error}`);
+    }
+    return;
+  }
+
+  fail('用法: openxiangda update check|install [--json] [--registry https://registry.npmjs.org] [--no-skills]');
+}
+
+function normalizeNpmRegistry(value) {
+  const registry = String(value || OFFICIAL_NPM_REGISTRY).trim();
+  return registry.replace(/\/+$/, '') || OFFICIAL_NPM_REGISTRY;
+}
+
+function checkOpenXiangdaUpdate(registry) {
+  const latestVersion = fetchLatestOpenXiangdaVersion(registry);
+  const versionComparison = compareVersions(latestVersion, CURRENT_VERSION);
+  const updateAvailable = versionComparison > 0;
+  return {
+    packageName: NPM_PACKAGE_NAME,
+    currentVersion: CURRENT_VERSION,
+    latestVersion,
+    registry,
+    updateAvailable,
+    status: updateAvailable
+      ? 'update_available'
+      : versionComparison < 0
+        ? 'local_newer_than_registry'
+        : 'latest',
+    installCommand: `npm install -g ${NPM_PACKAGE_NAME}@latest --registry=${registry}`,
+    skillInstallCommand: 'openxiangda skill install --force',
+    compatibilityCheckCommand: 'openxiangda commands --json',
+    checkedAt: new Date().toISOString(),
+    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.',
+    ],
+  };
+}
+
+function fetchLatestOpenXiangdaVersion(registry) {
+  const result = spawnSync(
+    'npm',
+    ['view', `${NPM_PACKAGE_NAME}@latest`, 'version', `--registry=${registry}`, '--json'],
+    {
+      encoding: 'utf8',
+      env: { ...process.env, npm_config_registry: registry },
+    }
+  );
+  if (result.error) {
+    fail(`无法执行 npm: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail(`检查 OpenXiangda 更新失败: ${formatSpawnOutput(result)}`);
+  }
+  const raw = String(result.stdout || '').trim();
+  if (!raw) fail('检查 OpenXiangda 更新失败: npm 未返回版本号');
+  try {
+    const parsed = JSON.parse(raw);
+    return String(parsed).trim();
+  } catch (_error) {
+    return raw.replace(/^"|"$/g, '').trim();
+  }
+}
+
+function installOpenXiangdaUpdate(registry, options = {}) {
+  const npmArgs = [
+    'install',
+    '-g',
+    `${NPM_PACKAGE_NAME}@latest`,
+    `--registry=${registry}`,
+  ];
+  const quiet = Boolean(options.json);
+  if (!quiet) {
+    print(`执行: npm ${npmArgs.join(' ')}`);
+  }
+  const installResult = spawnSync('npm', npmArgs, {
+    encoding: 'utf8',
+    stdio: quiet ? 'pipe' : 'inherit',
+    env: { ...process.env, npm_config_registry: registry },
+  });
+  if (installResult.error) {
+    fail(`无法执行 npm: ${installResult.error.message}`);
+  }
+  if (installResult.status !== 0) {
+    fail(`OpenXiangda 更新失败: ${formatSpawnOutput(installResult)}`);
+  }
+
+  const result = {
+    packageName: NPM_PACKAGE_NAME,
+    registry,
+    installCommand: `npm ${npmArgs.join(' ')}`,
+    installed: true,
+    skillInstall: {
+      attempted: false,
+      status: null,
+      error: null,
+    },
+  };
+
+  if (!options.skipSkills) {
+    if (!quiet) {
+      print('刷新 OpenXiangda skills: openxiangda skill install --force');
+    }
+    const skillResult = spawnSync('openxiangda', ['skill', 'install', '--force'], {
+      encoding: 'utf8',
+      stdio: quiet ? 'pipe' : 'inherit',
+      env: process.env,
+    });
+    result.skillInstall.attempted = true;
+    result.skillInstall.status = skillResult.status;
+    if (skillResult.error || skillResult.status !== 0) {
+      result.skillInstall.error = skillResult.error?.message || formatSpawnOutput(skillResult);
+    }
+  }
+
+  return result;
+}
+
+function printUpdateCheck(result) {
+  const lines = [
+    'OpenXiangda update check',
+    `current: ${result.currentVersion}`,
+    `latest: ${result.latestVersion}`,
+    `registry: ${result.registry}`,
+  ];
+  if (result.updateAvailable) {
+    lines.push('status: update available');
+    lines.push('recommended:');
+    lines.push(`  ${result.installCommand}`);
+    lines.push(`  ${result.skillInstallCommand}`);
+  } else if (result.status === 'local_newer_than_registry') {
+    lines.push('status: local version is newer than registry');
+  } else {
+    lines.push('status: already latest');
+  }
+  lines.push(`compatibility: ${result.compatibilityCheckCommand}`);
+  print(lines.join('\n'));
+}
+
+function formatSpawnOutput(result) {
+  return (
+    String(result.stderr || '').trim() ||
+    String(result.stdout || '').trim() ||
+    `exit status ${result.status}`
+  );
+}
+
+function compareVersions(a, b) {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  for (let index = 0; index < 3; index += 1) {
+    if (left.numbers[index] !== right.numbers[index]) {
+      return left.numbers[index] > right.numbers[index] ? 1 : -1;
+    }
+  }
+  if (left.prerelease === right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  return left.prerelease > right.prerelease ? 1 : -1;
+}
+
+function parseSemver(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(String(value || ''));
+  if (!match) {
+    return { numbers: [0, 0, 0], prerelease: String(value || '') };
+  }
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] || '',
+  };
+}
+
 async function platform(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
@@ -378,14 +578,49 @@ async function workspace(args) {
   const config = loadConfig();
 
   if (subcommand === 'init') {
+    let appType = flags['app-type'];
+    let profileName = flags.profile || null;
+    let createdApp = null;
+
+    if (flags['app-name']) {
+      if (appType) {
+        fail('workspace init 不能同时使用 --app-name 和 --app-type');
+      }
+      profileName = profileName || config.currentProfile;
+      if (!profileName) {
+        fail('workspace init --app-name 需要先选择 profile，或显式传 --profile <name>');
+      }
+      assertCanInitializeWorkspace({
+        dir: positional[0],
+        force: flags.force,
+      });
+      const data = await createPlatformApp(config, profileName, {
+        name: flags['app-name'],
+        description: flags.description || '',
+        iconfontCss: flags['iconfont-css'] || '',
+      });
+      appType = extractCreatedAppType(data);
+      if (!appType) {
+        fail('应用已创建，但平台响应缺少 appType，无法写入 workspace 绑定');
+      }
+      createdApp = {
+        name: flags['app-name'],
+        appType,
+        data,
+      };
+    }
+
     const result = initWorkspace({
       dir: positional[0],
       name: flags.name,
       install: flags.install,
       force: flags.force,
-      profile: flags.profile,
-      appType: flags['app-type'],
+      profile: profileName,
+      appType,
     });
+    if (createdApp) {
+      result.createdApp = createdApp;
+    }
     if (flags.json) return writeJson(result);
     printWorkspaceInitReport(result);
     return;
@@ -418,12 +653,14 @@ async function workspace(args) {
       },
       updatedAt: new Date().toISOString(),
     };
+    ensureResourceBuckets(state.profiles[profileName]);
     saveProjectState(state);
     print(`当前工作区已绑定 ${profileName}: ${appType}`);
     return;
   }
 
   if (subcommand === 'publish') {
+    const publishOptions = normalizeWorkspacePublishOptions(flags);
     const state = loadProjectState();
     const bound = state.profiles?.[profileName];
     if (!bound?.appType) {
@@ -436,15 +673,30 @@ async function workspace(args) {
       profileName,
       `/openxiangda-api/v1/apps/${encodeURIComponent(bound.appType)}/snapshot`
     );
-    runWorkspacePublish(profileName, profile, bound.appType);
-    await publishResourcesForWorkspace(config, profileName, {
-      quiet: true,
-      prune: Boolean(flags.prune),
-    });
+    runWorkspacePublish(profileName, profile, bound.appType, publishOptions.workspaceArgs);
+    if (publishOptions.includeResources) {
+      if (publishOptions.dryRun) {
+        const manifest = loadWorkspaceResources();
+        const validation = validateWorkspaceResources(manifest);
+        if (validation.errors.length > 0) {
+          fail(`资源配置校验失败: ${validation.errors[0]}`);
+        }
+        const target = getWorkspaceTarget(config, profileName, {});
+        const plan = await buildResourcePlan(config, target, manifest);
+        printResourcePlan(plan);
+      } else {
+        await publishResourcesForWorkspace(config, profileName, {
+          quiet: true,
+          prune: Boolean(flags.prune),
+        });
+      }
+    } else if (!publishOptions.quietResourceSkip) {
+      print('已跳过 src/resources 发布；如需同时发布资源，传 --resources。');
+    }
     return;
   }
 
-  fail('用法: openxiangda workspace init|bind|publish');
+  fail('用法: openxiangda workspace init|bind|publish [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources]');
 }
 
 async function app(args) {
@@ -463,13 +715,10 @@ async function app(args) {
   if (subcommand === 'create') {
     const name = flags.name || positional.join(' ');
     if (!name) fail('用法: openxiangda app create <name> [--profile name]');
-    const data = await requestWithAuth(config, profileName, '/openxiangda-api/v1/apps/', {
-      method: 'POST',
-      body: {
-        name,
-        description: flags.description || '',
-        iconfontCss: flags['iconfont-css'] || '',
-      },
+    const data = await createPlatformApp(config, profileName, {
+      name,
+      description: flags.description || '',
+      iconfontCss: flags['iconfont-css'] || '',
     });
     if (flags.json) return writeJson(data);
     print(JSON.stringify(data, null, 2));
@@ -490,6 +739,29 @@ async function app(args) {
   print(JSON.stringify(data, null, 2));
 }
 
+async function createPlatformApp(config, profileName, payload) {
+  return requestWithAuth(config, profileName, '/openxiangda-api/v1/apps/', {
+    method: 'POST',
+    body: {
+      name: payload.name,
+      description: payload.description || '',
+      iconfontCss: payload.iconfontCss || '',
+    },
+  });
+}
+
+function extractCreatedAppType(data) {
+  const candidates = [
+    data?.appType,
+    data?.app?.appType,
+    data?.result?.appType,
+    data?.application?.appType,
+    data?.type,
+  ];
+  const value = candidates.find(item => typeof item === 'string' && item.trim());
+  return value ? value.trim() : null;
+}
+
 async function form(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
@@ -1800,10 +2072,11 @@ async function commands(args) {
     name: 'openxiangda',
     commands: [
       'login <platform-url> [--profile name]',
+      'update check|install',
       'platform add|list|use|remove',
       'auth status|refresh|logout',
       'env',
-      'workspace init|bind|publish [--prune]',
+      'workspace init|bind|publish [--app-name] [--changed|--since|--form|--page|--only|--dry-run|--force|--resources|--skip-resources|--prune]',
       'app list|create|snapshot',
       'form list|create|bind|pull|publish',
       'page list|publish|bind|releases|activate',
@@ -1828,6 +2101,9 @@ function printWorkspaceInitReport(result) {
     `已创建 OpenXiangda workspace: ${result.targetDir}`,
     `package: ${result.packageName}`,
   ];
+  if (result.createdApp) {
+    lines.push(`已创建平台应用: ${result.createdApp.name} (${result.createdApp.appType})`);
+  }
   if (result.bound) {
     lines.push(`已绑定 ${result.bound.profile}: ${result.bound.appType}`);
   }
@@ -4810,7 +5086,60 @@ async function refreshProfile(config, profileName) {
   };
 }
 
-function runWorkspacePublish(profileName, profile, appType) {
+function readStringFlag(flags, key) {
+  const value = flags[key];
+  if (value === undefined || value === null || value === false) return '';
+  if (value === true) fail(`--${key} 需要提供值`);
+  return String(value).trim();
+}
+
+function normalizeWorkspacePublishOptions(flags) {
+  const targetForm = readStringFlag(flags, 'form');
+  const targetPage = readStringFlag(flags, 'page');
+  const only = readStringFlag(flags, 'only');
+  const since = readStringFlag(flags, 'since');
+  const changed = Boolean(flags.changed || flags['changed-only']);
+  const dryRun = Boolean(flags['dry-run']);
+  const force = Boolean(flags.force);
+  const skipResources = Boolean(flags['skip-resources']);
+  const includeResourcesFlag = Boolean(flags.resources || flags['include-resources']);
+  const prune = Boolean(flags.prune);
+
+  if (targetForm && targetPage) {
+    fail('workspace publish 不能同时使用 --form 和 --page，请分两次发布');
+  }
+  if (changed && (targetForm || targetPage || only)) {
+    fail('workspace publish --changed 不能与 --form、--page 或 --only 同时使用');
+  }
+  if (since && !changed) {
+    fail('workspace publish --since 只能与 --changed 一起使用');
+  }
+  if (skipResources && prune) {
+    fail('workspace publish --skip-resources 不能与 --prune 同时使用');
+  }
+
+  const workspaceArgs = [];
+  if (targetForm) workspaceArgs.push('--form', targetForm);
+  if (targetPage) workspaceArgs.push('--page', targetPage);
+  if (only) workspaceArgs.push('--only', only);
+  if (changed) workspaceArgs.push('--changed');
+  if (since) workspaceArgs.push('--since', since);
+  if (dryRun) workspaceArgs.push('--dry-run');
+  if (force) workspaceArgs.push('--force');
+
+  const targeted = Boolean(targetForm || targetPage || only || changed);
+  const includeResources =
+    !skipResources && (includeResourcesFlag || prune || !targeted);
+
+  return {
+    workspaceArgs,
+    dryRun,
+    includeResources,
+    quietResourceSkip: !targeted || skipResources,
+  };
+}
+
+function runWorkspacePublish(profileName, profile, appType, publishArgs = []) {
   const packageFile = path.join(process.cwd(), 'package.json');
   if (!fs.existsSync(packageFile)) {
     fail('当前目录没有 package.json，无法识别工作区发布脚本');
@@ -4828,7 +5157,9 @@ function runWorkspacePublish(profileName, profile, appType) {
 
   const usePnpm = fs.existsSync(path.join(process.cwd(), 'pnpm-lock.yaml'));
   const command = usePnpm ? 'pnpm' : 'npm';
-  const args = usePnpm ? ['run', scriptName] : ['run', scriptName];
+  const args = publishArgs.length
+    ? ['run', scriptName, '--', ...publishArgs]
+    : ['run', scriptName];
   const result = spawnSync(command, args, {
     cwd: process.cwd(),
     stdio: 'inherit',

package/lib/workspace-init.js

@@ -41,8 +41,14 @@ function initWorkspace(options = {}) {
             automations: {},
             menus: {},
             roles: {},
+            connectors: {},
+            notifications: {
+              templates: {},
+              typeConfigs: {},
+            },
             pagePermissionGroups: {},
             formPermissionGroups: {},
+            formSettings: {},
           },
           updatedAt: new Date().toISOString(),
         },
@@ -69,6 +75,12 @@ function initWorkspace(options = {}) {
   };
 }
 
+function assertCanInitializeWorkspace(options = {}) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+  ensureCanInitialize(targetDir, Boolean(options.force));
+  return targetDir;
+}
+
 function ensureCanInitialize(targetDir, force) {
   if (!fs.existsSync(TEMPLATE_DIR)) {
     throw new Error(`workspace 模板不存在: ${TEMPLATE_DIR}`);
@@ -135,5 +147,6 @@ function buildNextSteps(targetDir, installedDependencies, bound) {
 }
 
 module.exports = {
+  assertCanInitializeWorkspace,
   initWorkspace,
 };

package/openxiangda-skills/SKILL.md

@@ -35,27 +35,36 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
    ```bash
    openxiangda login https://dev-lowcode.example.com --profile dev
    ```
-4. Check current context before any write:
+4. Check the CLI version and current context before any write:
    ```bash
+   openxiangda update check --json
    openxiangda env --profile dev
    openxiangda auth status --profile dev
    ```
-5. Ensure there is a local app workspace. If the current directory is not a `sy-lowcode-app-workspace` and no app workspace exists yet, initialize one:
+   If `updateAvailable` is true, update from the official npm registry before continuing:
    ```bash
-   openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+   openxiangda update install
+   ```
+5. Ensure there is a local app workspace. Local workspace state is authoritative:
+   - If the current workspace already has `.openxiangda/state.json` with an app binding for the target profile, use that app.
+   - If the user explicitly provides an `appType` or asks to reuse an existing app, bind to that exact app.
+   - If the current folder is empty or has no local app binding, create a new app and workspace; do not search the platform for similar app names.
+   ```bash
+   openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
    cd ./my-app-workspace
    pnpm install
    ```
-6. Bind the local workspace to the app for the selected platform:
+6. To bind an existing app only when explicitly requested:
    ```bash
-   openxiangda app list --profile dev
-   # or create one when needed:
-   openxiangda app create "示例应用" --profile dev
+   openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+   # or, inside an existing workspace:
    openxiangda workspace bind --profile dev --app-type APP_XXXX
-   cd /path/to/sy-lowcode-app-workspace
+   ```
+7. Publish from the local workspace:
+   ```bash
    openxiangda workspace publish --profile dev
    ```
-7. For multi-platform publishing, always pass `--profile` explicitly:
+8. For multi-platform publishing, always pass `--profile` explicitly:
    ```bash
    openxiangda workspace publish --profile prod
    ```
@@ -63,14 +72,19 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 ## Rules
 
 - Never ask the user for `appKey`, `appSecret`, `AK`, or `SK`.
-- If `openxiangda` is not available in PATH, the CLI package is not installed or linked. In this repo, use `npm link`; in a packaged install, use `npm install -g .` or the published package.
+- If `openxiangda` is not available in PATH, the CLI package is not installed or linked. In this repo, use `npm link`; in a packaged install, use `npm install -g openxiangda@latest --registry=https://registry.npmjs.org`.
+- Always prefer the official npm registry for OpenXiangda updates. Domestic mirrors may lag and return an older package.
+- Run `openxiangda update check --json` when starting substantial work or diagnosing version/skill mismatches. If it reports an update, run `openxiangda update install` so the CLI and installed skills match. If the installed CLI does not support `update`, run `npm install -g openxiangda@latest --registry=https://registry.npmjs.org` and then `openxiangda skill install --force`.
+- Local `.openxiangda/state.json` is the source of truth for app binding. In an empty folder or unbound workspace, create a new app with `workspace init --app-name`; do not infer reuse from similar platform app names.
 - If there is no `sy-lowcode-app-workspace`, create one with `openxiangda workspace init <dir>` before writing forms, pages, or JS_CODE nodes.
 - Never treat `openxiangda form create` as page generation. It only creates a low-level platform form shell for diagnostics or for workspace publish internals. The source of user-facing pages is `sy-lowcode-app-workspace`.
 - Publish normal form pages, workflow form pages, and custom code pages through `openxiangda workspace publish --profile <name>` from the app workspace.
+- For routine AI edits, avoid reflexive full publish. First run `openxiangda workspace publish --profile <name> --changed --dry-run`, then use `--changed`, `--page <pageCode>`, `--form <formCode>`, or `--only pages/a,forms/b`. Use full publish only when broad shared/config changes intentionally affect many modules.
 - Never store token data in the project directory. User tokens live in `~/.openxiangda/profiles.json`; project state lives in `.openxiangda/state.json` and stores only IDs and mappings.
 - Use logical resource codes in local files. Platform-specific IDs such as `formUuid`, `pageId`, `workflowId`, and `automationId` must be isolated by profile.
 - Put engineering-managed resources in `src/resources/` and use `openxiangda resource validate|plan|publish|pull`. `workspace publish` publishes workspace forms/pages first, then runs non-destructive resource upsert. Only pass `--prune` when the user explicitly wants local manifests to delete platform-side extras.
 - For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.
+- Before scaffolding a real app, complex page, data management page, portal shell, status lifecycle, role governance, or automation, read `references/best-practices.md` and pick the architecture first. Prefer copying the relevant pattern from `examples/best-practices/` into `src/` instead of generating a single large page file.
 - Before publishing to another platform, verify the workspace is bound for that profile. Resource IDs from one profile must not be reused for another profile.
 - Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` for diagnosis before changing an existing app.
 - Run write commands that update `.openxiangda/state.json` sequentially within the same workspace. Read-only commands can run in parallel.
@@ -106,6 +120,7 @@ Core CLI / state:
 - `references/workspace-state.md` — `.openxiangda/state.json` shape and profile isolation rules.
 - `references/connector-resources.md` — `src/resources` manifests, connector schema, and SDK connector calls.
 - `references/notifications.md` — `src/resources/notifications`, notification templates/type bindings, and `sdk.notification` / `ctx.notification`.
+- `references/best-practices.md` — initialized examples for modular pages, state lifecycles, role governance, permission isolation, high-performance queries, portal shells, workflow boundaries, and automation patterns.
 
 Form authoring:
 
@@ -130,5 +145,6 @@ Platform domain knowledge (read these first when generating forms or pages so th
 - `references/platform-data-model.md` — how the platform persists field values (JSONB, `{label, value}` for option fields, attachment shape, etc.). Use this whenever you write, render, or diagnose form data.
 - `references/style-system.md` — three-layer style architecture, CSS namespace, and the no-hardcoded-color rule. Use this before writing any page or form CSS.
 - `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, recommended directory layout for `src/pages` and `src/forms`. Use this before scaffolding a new page or list view.
+- `references/best-practices.md` — read this before implementing app-level business patterns; it points to `examples/best-practices/` and explains when to use status fields instead of workflow.
 - `references/component-guide.md` — when to pick platform components vs. raw Ant Design vs. custom components, with the rules for option fields. Use this before introducing a new component.
 - `references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and how to fix them. Use this when something does not behave as expected.