openxiangda 1.0.35 → 1.0.37

package/README.md

@@ -79,8 +79,20 @@ 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.
 
+For existing app workspaces created before AGENTS.md / `.qoder/rules/` / `.cursor/rules/` / `scripts/guard-publish.mjs` / `package.json` `_guard:publish` were added, run:
+
+```bash
+openxiangda skill bootstrap                 # current dir, dry-run by default? no — write
+openxiangda skill bootstrap --dry-run --json # preview
+openxiangda skill bootstrap --force          # overwrite drifted local copies
+```
+
+It copies the AI-guidance bundle (AGENTS.md, Qoder/Cursor always-on + glob rules, the publish guard script) and patches `package.json` with the `_guard:publish` script plus `prepublish:all` / `prepublish:oss` / `preregister` / `preregister-bundle` / `prepublish:changed` / `preopenxiangda:publish` hooks so that direct `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` calls fail-fast unless invoked through `openxiangda workspace publish ...`.
+
 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.
 
+New OpenXiangda code pages and form custom pages publish with `cssIsolation: "none"` by default, so Tailwind utilities and normal Ant Design styles apply without a `.sy-app-workspace` prefix. Explicit `namespace` and `shadow` settings are kept only for legacy compatibility.
+
 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

package/lib/cli.js

@@ -20,6 +20,7 @@ const {
 const { requestJson } = require('./http');
 const { getSkillStatusReport, installSkills } = require('./skills');
 const { assertCanInitializeWorkspace, initWorkspace } = require('./workspace-init');
+const { bootstrapWorkspace } = require('./workspace-bootstrap');
 const {
   fail,
   maskText,
@@ -116,6 +117,7 @@ Usage:
   openxiangda feedback preview|submit --summary <text> [--type bug] [--severity medium] [--profile name] [--yes]
   openxiangda skill install [--agent codex|claude|qoder|dual] [--dest <skills-dir>] [--force] [--dry-run] [--json]
   openxiangda skill status [--agent codex|claude|qoder|dual] [--dest <skills-dir>] [--json]
+  openxiangda skill bootstrap [<dir>] [--force] [--dry-run] [--json]
 
 OpenXiangda 使用普通用户登录 token，不需要 AK/SK。
 表单页、流程表单页和代码页的主链路是 sy-lowcode-app-workspace + openxiangda workspace publish。
@@ -1482,7 +1484,7 @@ async function page(args) {
             jsUrls: splitList(flags['js-urls']),
             framework: flags.framework || 'react',
             frameworkVersion: flags['framework-version'] || '',
-            cssIsolation: flags['css-isolation'] || 'namespace',
+            cssIsolation: flags['css-isolation'] || 'none',
             format: flags.format || 'esm',
           },
           menu: flags.menu
@@ -2681,7 +2683,7 @@ async function commands(args) {
       'resource validate|plan|publish|pull',
       'inspect app|form|workflow|automation|permissions',
       'feedback preview|submit',
-      'skill install|status',
+      'skill install|status|bootstrap',
     ],
   };
   if (flags.json) return writeJson(manifest);
@@ -2711,7 +2713,7 @@ function printWorkspaceInitReport(result) {
 
 async function skill(args) {
   const [subcommand, ...rest] = args;
-  const { flags } = parseArgs(rest);
+  const { flags, positional } = parseArgs(rest);
   const options = {
     agent: flags.agent || 'codex',
     dest: flags.dest,
@@ -2733,7 +2735,18 @@ async function skill(args) {
     return;
   }
 
-  fail('用法: openxiangda skill install|status [--agent codex|claude|qoder|dual] [--dest <skills-dir>]');
+  if (subcommand === 'bootstrap') {
+    const result = bootstrapWorkspace({
+      dir: positional[0],
+      force: Boolean(flags.force),
+      dryRun: Boolean(flags['dry-run']),
+    });
+    if (flags.json) return writeJson(result);
+    printSkillBootstrapReport(result);
+    return;
+  }
+
+  fail('用法: openxiangda skill install|status [--agent codex|claude|qoder|dual] [--dest <skills-dir>]\n      openxiangda skill bootstrap [<dir>] [--force] [--dry-run] [--json]');
 }
 
 function printSkillInstallReport(result) {
@@ -2792,6 +2805,33 @@ function printSkillStatusReport(result) {
   }
 }
 
+function printSkillBootstrapReport(result) {
+  const lines = [
+    `OpenXiangda skill bootstrap${result.dryRun ? ' (dry-run)' : ''}`,
+    `Workspace: ${result.targetDir}`,
+  ];
+  for (const file of result.files) {
+    const reason = file.reason ? ` — ${file.reason}` : '';
+    lines.push(`- ${file.path}: ${file.action}${reason}`);
+  }
+  const pkg = result.packageJson;
+  const pkgReason = pkg.reason ? ` — ${pkg.reason}` : '';
+  lines.push(`- ${pkg.path}: ${pkg.action}${pkgReason}`);
+  if (pkg.added && pkg.added.length > 0) {
+    lines.push(`  + scripts: ${pkg.added.join(', ')}`);
+  }
+  if (pkg.changed && pkg.changed.length > 0) {
+    lines.push(`  ~ scripts: ${pkg.changed.join(', ')}`);
+  }
+  lines.push(`Summary: ${result.summary}`);
+  if (result.dryRun) {
+    lines.push('dry-run completed; no files were changed');
+  } else {
+    lines.push('Done. 重启 Qoder / Cursor / Claude / Codex 以加载新的 always-on rules。');
+  }
+  print(lines.join('\n'));
+}
+
 function getWorkspaceTarget(config, profileName, flags = {}) {
   const resolved = getProfile(config, profileName);
   const state = loadProjectState();

package/lib/workspace-bootstrap.js

@@ -0,0 +1,238 @@
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.join(__dirname, '..');
+const TEMPLATE_DIR = path.join(ROOT_DIR, 'templates', 'sy-lowcode-app-workspace');
+
+// AI 引导/守卫"四件套 + glob rules"清单。
+// 这些路径是相对于 workspace 根，文件源都来自 templates/sy-lowcode-app-workspace。
+const BOOTSTRAP_FILES = [
+  'AGENTS.md',
+  'scripts/guard-publish.mjs',
+  '.qoder/rules/openxiangda.md',
+  '.qoder/rules/openxiangda-form.md',
+  '.qoder/rules/openxiangda-page.md',
+  '.qoder/rules/openxiangda-workflow-automation.md',
+  '.qoder/rules/openxiangda-resources.md',
+  '.cursor/rules/openxiangda.mdc',
+  '.cursor/rules/openxiangda-form.mdc',
+  '.cursor/rules/openxiangda-page.mdc',
+  '.cursor/rules/openxiangda-workflow-automation.mdc',
+  '.cursor/rules/openxiangda-resources.mdc',
+];
+
+// package.json 必须存在的守卫脚本与 prefoo hook。
+const PACKAGE_JSON_GUARD_SCRIPTS = {
+  '_guard:publish': 'node scripts/guard-publish.mjs',
+  'prepublish:all': 'pnpm _guard:publish',
+  'prepublish:oss': 'pnpm _guard:publish',
+  'preregister': 'pnpm _guard:publish',
+  'preregister-bundle': 'pnpm _guard:publish',
+  'prepublish:changed': 'pnpm _guard:publish',
+  'preopenxiangda:publish': 'pnpm _guard:publish',
+};
+
+function bootstrapWorkspace(options = {}) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options.dryRun);
+
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    throw new Error(`workspace 模板不存在: ${TEMPLATE_DIR}`);
+  }
+  if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+    throw new Error(`目标目录不存在或不是目录: ${targetDir}`);
+  }
+
+  const fileOps = BOOTSTRAP_FILES.map(rel => planFileOp(rel, targetDir, force));
+  const packageJsonOp = planPackageJsonOp(targetDir, force);
+
+  if (!dryRun) {
+    for (const op of fileOps) {
+      if (op.action === 'install' || op.action === 'overwrite') {
+        ensureDir(path.dirname(op.targetPath));
+        fs.copyFileSync(op.sourcePath, op.targetPath);
+      }
+    }
+    if (packageJsonOp.action === 'patch' || packageJsonOp.action === 'create-scripts') {
+      writePackageJson(packageJsonOp.targetPath, packageJsonOp.nextContent);
+    }
+  }
+
+  return {
+    targetDir,
+    dryRun,
+    force,
+    files: fileOps.map(op => ({
+      path: op.relativePath,
+      action: op.action,
+      reason: op.reason || null,
+    })),
+    packageJson: {
+      path: packageJsonOp.relativePath,
+      action: packageJsonOp.action,
+      added: packageJsonOp.added || [],
+      changed: packageJsonOp.changed || [],
+      reason: packageJsonOp.reason || null,
+    },
+    summary: buildSummary(fileOps, packageJsonOp),
+  };
+}
+
+function planFileOp(relativePath, targetDir, force) {
+  const sourcePath = path.join(TEMPLATE_DIR, relativePath);
+  const targetPath = path.join(targetDir, relativePath);
+  if (!fs.existsSync(sourcePath)) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'missing-source',
+      reason: '模板缺失，请升级 openxiangda',
+    };
+  }
+  const sourceContent = fs.readFileSync(sourcePath);
+  if (!fs.existsSync(targetPath)) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'install',
+    };
+  }
+  const targetContent = fs.readFileSync(targetPath);
+  if (sourceContent.equals(targetContent)) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'unchanged',
+    };
+  }
+  if (force) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'overwrite',
+    };
+  }
+  return {
+    relativePath,
+    sourcePath,
+    targetPath,
+    action: 'skip',
+    reason: '本地版本与模板不同；如需覆盖请传 --force',
+  };
+}
+
+function planPackageJsonOp(targetDir, force) {
+  const targetPath = path.join(targetDir, 'package.json');
+  const relativePath = 'package.json';
+  if (!fs.existsSync(targetPath)) {
+    return {
+      targetPath,
+      relativePath,
+      action: 'absent',
+      reason: 'package.json 不存在；不是 npm 工作区',
+    };
+  }
+  const raw = fs.readFileSync(targetPath, 'utf8');
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch (error) {
+    return {
+      targetPath,
+      relativePath,
+      action: 'invalid-json',
+      reason: `package.json 解析失败: ${error.message}`,
+    };
+  }
+  const scripts = pkg.scripts ? { ...pkg.scripts } : null;
+  if (!scripts) {
+    const nextPkg = { ...pkg, scripts: { ...PACKAGE_JSON_GUARD_SCRIPTS } };
+    return {
+      targetPath,
+      relativePath,
+      action: 'create-scripts',
+      added: Object.keys(PACKAGE_JSON_GUARD_SCRIPTS),
+      changed: [],
+      nextContent: stringifyPackageJson(raw, nextPkg),
+    };
+  }
+  const added = [];
+  const changed = [];
+  for (const [name, value] of Object.entries(PACKAGE_JSON_GUARD_SCRIPTS)) {
+    if (!(name in scripts)) {
+      scripts[name] = value;
+      added.push(name);
+    } else if (scripts[name] !== value) {
+      if (force) {
+        scripts[name] = value;
+        changed.push(name);
+      } else {
+        changed.push(`${name} (skipped, value differs; pass --force to overwrite)`);
+      }
+    }
+  }
+  if (added.length === 0 && changed.length === 0) {
+    return {
+      targetPath,
+      relativePath,
+      action: 'unchanged',
+      added: [],
+      changed: [],
+    };
+  }
+  const nextPkg = { ...pkg, scripts };
+  return {
+    targetPath,
+    relativePath,
+    action: 'patch',
+    added,
+    changed,
+    nextContent: stringifyPackageJson(raw, nextPkg),
+  };
+}
+
+function stringifyPackageJson(originalRaw, nextPkg) {
+  const indent = detectIndent(originalRaw);
+  const trailingNewline = originalRaw.endsWith('\n') ? '\n' : '';
+  return `${JSON.stringify(nextPkg, null, indent)}${trailingNewline}`;
+}
+
+function detectIndent(raw) {
+  const match = raw.match(/^(\s+)\"/m);
+  if (!match) return 2;
+  if (match[1].includes('\t')) return '\t';
+  return match[1].length;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writePackageJson(targetPath, nextContent) {
+  fs.writeFileSync(targetPath, nextContent);
+}
+
+function buildSummary(fileOps, packageJsonOp) {
+  const counts = { install: 0, overwrite: 0, unchanged: 0, skip: 0 };
+  for (const op of fileOps) {
+    if (counts[op.action] !== undefined) counts[op.action] += 1;
+  }
+  const parts = [];
+  parts.push(`installed=${counts.install}`);
+  parts.push(`overwritten=${counts.overwrite}`);
+  parts.push(`unchanged=${counts.unchanged}`);
+  parts.push(`skipped=${counts.skip}`);
+  parts.push(`package.json=${packageJsonOp.action}`);
+  return parts.join(' ');
+}
+
+module.exports = {
+  BOOTSTRAP_FILES,
+  PACKAGE_JSON_GUARD_SCRIPTS,
+  bootstrapWorkspace,
+};

package/openxiangda-skills/SKILL.md

@@ -1,13 +1,51 @@
 ---
 name: openxiangda
-description: Use OpenXiangda to help AI agents build and publish apps on a private low-code platform through the openxiangda CLI, ordinary user login tokens, platform profiles, workspace initialization, workspace binding, and app snapshots; use when the user mentions OpenXiangda, 湘搭, 私有化低代码平台, sy-lowcode-app-workspace, profile/domain login, or multi-platform publishing.
+description: Use OpenXiangda for ANY work inside a sy-lowcode-app-workspace or any private low-code platform (OpenXiangda / 湘搭 / 私有化低代码) — publishing / 发布 / 上线 / deploying / 部署 / shipping / releasing / 上传 / pushing apps, pages, forms, workflows, automations; creating / scaffolding / 创建 / 搭建 / 新建 apps, code pages, form pages, workflow forms, JS_CODE nodes; editing / 修改 / 编辑 schemas, options, fields, layouts, menus; managing / 管理 roles, page permission groups, form permission groups, form settings, public access, data views, connectors, notifications; diagnosing / 排查 / 诊断 / 看快照 app snapshots, executions, logs, version drift, profile isolation, token / login / profile issues; running the openxiangda CLI or anything that touches `.openxiangda/state.json`, `~/.openxiangda/profiles.json`, `/openxiangda-api/v1`, `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE`, `app-workspace.config.ts`. Trigger when the user mentions OpenXiangda / 湘搭 / 私有化低代码 / 低代码平台 / sy-lowcode-app-workspace, or when the workspace contains `.openxiangda/state.json` or `app-workspace.config.ts`. Always prefer this skill over running `pnpm publish:all`, `pnpm publish:oss`, `pnpm register`, or `lowcode-workspace publish-*` directly.
 ---
 
 # OpenXiangda
 
-OpenXiangda is a lightweight bridge between an AI coding tool and a private low-code platform. It does not ask users for AK/SK. The user provides a platform domain, logs in as a normal platform user, and the CLI calls `/openxiangda-api/v1` with that user's token.
+OpenXiangda is a lightweight bridge between an AI coding tool and a private low-code platform. No AK/SK. The user provides a platform domain, logs in as a normal platform user, and the CLI calls `/openxiangda-api/v1` with that user's token.
 
-For page generation, OpenXiangda must use `sy-lowcode-app-workspace`: form pages, workflow form pages, and custom code pages are implemented as workspace source files, built into bundles, uploaded to OSS, and registered through `openxiangda workspace publish`. Do not generate final user-facing pages by relying on the platform's legacy default schema page.
+For any user-facing page (form pages, workflow form pages, custom code pages), OpenXiangda must use `sy-lowcode-app-workspace`: source files in `src/`, built into bundles, uploaded to OSS, and registered through `openxiangda workspace publish`. Do not rely on the platform's legacy default schema page.
+
+## TL;DR — Decision Card
+
+**If the workspace has `.openxiangda/state.json` or `app-workspace.config.ts`, you are in an OpenXiangda app workspace. Read this card before any tool call.**
+
+### Routing — user intent → skill / command
+
+| User says (zh / en) | Skill | First command |
+|---|---|---|
+| 发布 / 上线 / 部署 / publish / deploy / ship / release | `openxiangda-core` | `openxiangda workspace publish --profile <name> --changed --dry-run` |
+| 只发布改动 / 增量 / 单页 / 单表 | `openxiangda-core` | `... --changed` / `--page <code>` / `--form <code>` / `--only pages/a,forms/b` |
+| 创建应用 / 新建 app / scaffold / 初始化工作区 | `openxiangda-app` | `openxiangda workspace init <dir> --profile <name> --app-name "..."` |
+| 绑定已有应用 / bind existing app | `openxiangda-app` | `openxiangda workspace bind --profile <name> --app-type APP_XXX` |
+| 创建 / 修改表单字段 / 表单页 / schema | `openxiangda-form` | edit `src/forms/<code>/{schema.ts,page.tsx}` → `workspace publish --form <code>` |
+| 创建 / 修改自定义代码页 / portal / dashboard | `openxiangda-page` | edit `src/pages/<code>/` → `workspace publish --page <code>` |
+| 审批流程 / workflow / 流程节点 / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow validate / create / publish` |
+| 自动化 / 定时任务 / 提交触发 / cron | `openxiangda-workflow-automation` | `openxiangda automation validate / create / publish / enable` |
+| 角色 / 权限组 / 字段权限 / 数据范围 / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot <APP_XXX> --profile <name> --json` |
+| 登录 / 切换平台 / profile / token / whoami | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
+| 多表只读联表查询 / 报表数据源 | `openxiangda-form` (data view) | declare `src/resources/data-views/<code>.json` → `resource publish` |
+| 调外部 / 第三方 API / 钉钉 / 自建系统 | `openxiangda-page` (connector) | declare `src/resources/connectors/<code>.json` → `sdk.connector.invoke` |
+
+### Hard rules — always
+
+- ✅ Publish through `openxiangda workspace publish --profile <name>` (with `--changed` / `--page` / `--form` / `--only` for routine edits).
+- ✅ User token lives in `~/.openxiangda/profiles.json`; project state in `.openxiangda/state.json` (IDs only).
+- ✅ Each profile (dev / prod / ...) has its own `appType` and resource IDs; never copy a `formUuid` / `pageId` / `workflowId` / `automationId` across profiles.
+- ✅ Run `openxiangda update check --json` at the start of substantial work; if `updateAvailable`, run `openxiangda update install` and `openxiangda skill install --force`.
+
+### Hard rules — never
+
+- ❌ `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*` directly — they are workspace internals and miss the profile token injection. Use `openxiangda workspace publish ...` instead.
+- ❌ Asking the user for `AK` / `SK` / `appKey` / `appSecret`. The whole flow is normal-user token only.
+- ❌ Searching the platform for a similar app name when `.openxiangda/state.json` has no binding — create a new app with `workspace init --app-name`.
+- ❌ Using `openxiangda form create` / `form publish` / `page publish` as the normal page generation path. They are low-level repair commands.
+- ❌ Running a full publish after editing one file. Default to `--changed --dry-run` → `--changed`, or targeted `--page` / `--form`.
+- ❌ Storing tokens, AK, SK, or third-party API secrets in project files. Shared env (`APP_OSS_*`, feedback robot) goes to `~/.openxiangda/.env`.
 
 ## Platform Routing
 
@@ -128,6 +166,7 @@ Core CLI / state:
 - `references/openxiangda-api.md` — `/openxiangda-api/v1` request and response fields.
 - `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/resource-manifest-cheatsheet.md` — 复制即用的 connector / data-view / notification / workflow / automation / JS_CODE / role / permission group / settings / menu manifest 骨架与运行时调用示例。在创建任何 `src/resources/` 资源前先看这份。
 - `references/data-views.md` — `src/resources/data-views` materialized view resources, DSL, permissions, refresh, CLI commands, and runtime SDK usage.
 - `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.
@@ -153,7 +192,7 @@ Workflow / automation / permissions:
 Platform domain knowledge (read these first when generating forms or pages so the output matches the live platform behavior):
 
 - `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 flexible Tailwind/CSS guidance. Use this before writing substantial page or form CSS.
+- `references/style-system.md` — style isolation defaults, legacy namespace compatibility, and flexible Tailwind/CSS guidance. Use this before writing substantial 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.

package/openxiangda-skills/references/component-guide.md

@@ -102,19 +102,18 @@ export function CustomSelect({ options, className, ...rest }: CustomSelectProps)
   return (
     <Select
       className={clsx('w-full rounded-md', className)}
-      popupClassName="sy-app-workspace"
-      getPopupContainer={(trigger) => trigger.parentElement ?? document.body}
-      options={options}
-      {...rest}
+      getPopupContainer={(trigger) => trigger.parentElement ?? document.body}
+      options={options}
+      {...rest}
     />
   );
 }
 ```
 
-要点：
-- 透传 `...rest`，保留 antd 全部 API。
-- `popupClassName="sy-app-workspace"` 确保弹层应用平台样式作用域。
-- `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
+要点：
+- 透传 `...rest`，保留 antd 全部 API。
+- `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
+- 默认 `cssIsolation: "none"` 时不要额外给弹层加 `sy-app-workspace`；只有 legacy `namespace/shadow` 页面才需要给弹层或容器补 namespace class。
 - 使用 `w-full`、`rounded-md`、`text-slate-600`、`border-slate-200` 等 Tailwind 原生类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 任意值或局部 CSS。
 
 ### 4.2 错误：从头实现选择器
@@ -171,7 +170,7 @@ function BadSelect({ options }) {
    </ConfigProvider>
    ```
 
-4. **谨慎**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）属于私有 API，升级风险较高。确实需要时必须限定在页面根类或 `.sy-app-workspace` 下，并优先考虑 `ConfigProvider`、`className`、组件 props 或 CSS 变量是否能解决。
+4. **谨慎**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）属于私有 API，升级风险较高。确实需要时必须限定在页面根类下；legacy 页面也可以兼容限定在 `.sy-app-workspace` 下。优先考虑 `ConfigProvider`、`className`、组件 props 或 CSS 变量是否能解决。
 
 ---
 
@@ -208,7 +207,7 @@ export function ActionButton(props) {
 | 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
 | 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
 | 常规组件大量写 `style={{ color: '#333', padding: 16 }}` | 优先 Tailwind 原生工具类、任意值或局部 CSS；动态值和少量精调 inline style 可接受 |
-| Select / Date / Modal 弹层错位、被滚动容器裁切 | 加 `getPopupContainer={(trigger) => trigger.parentElement}`，并在弹层 `popupClassName` 上加 `sy-app-workspace` |
+| Select / Date / Modal 弹层错位、被滚动容器裁切 | 默认加 `getPopupContainer={(trigger) => trigger.parentElement}`；legacy `namespace/shadow` 页面才额外使用 `sy-app-workspace` |
 | 不分端，PC 组件直接放移动端 | 按端拆页 + 端内用对应 UI 库 |
 | 无作用域覆盖 `.ant-xxx` 内部 class | 优先用 `className`、CSS 变量或 `ConfigProvider` 主题；必要覆盖时限定到页面命名空间 |
 | 在自定义组件中不透传 `...rest` / `ref` | 透传 props 与 `forwardRef`，保留底层组件全部能力 |
@@ -220,5 +219,5 @@ export function ActionButton(props) {
 - [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
 - [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
 - [ ] 样式 → 默认用 Tailwind 原生类 / 任意值 / 局部 CSS；平台 token 只在主题兼容或平台组件需要时使用，且作用域收敛？
-- [ ] 弹层 → 设置了 `getPopupContainer` 与 `sy-app-workspace` 弹层样式作用域？
+- [ ] 弹层 → 默认使用正常容器；只有 legacy 隔离页面才额外设置 `sy-app-workspace` 样式作用域？
 - [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？