openxiangda 1.0.0

package/openxiangda-skills/references/troubleshooting.md

@@ -0,0 +1,246 @@
+# OpenXiangda 常见问题排查指南
+
+> 本文档面向 AI Agent，收录在实际低代码项目（如 zjnu-dxyq-lowcode）开发中遇到的典型问题及解决方案。遇到报错或异常现象时，请优先在此查找匹配项；若无匹配，再结合源码与日志分析。
+
+## 快速索引
+
+| # | 问题 | 关键报错 / 现象 |
+| --- | --- | --- |
+| 1 | antd/antd-mobile 弹层样式丢失 | Select/Modal 弹层无样式或跑到屏幕外 |
+| 2 | SelectField options 为 undefined 导致 .map 报错 | `Cannot read properties of undefined (reading 'map')` |
+| 3 | ESM 模块动态导入路径错误 | `ERR_UNSUPPORTED_ESM_URL_SCHEME` / `Cannot find module` |
+| 4 | Windows 环境 OSS 上传路径错误 | 发布后资源 404，URL 含 `\` |
+| 5 | 构建时表单 API 常量替换失败 | formApi.ts 中环境变量未替换 |
+| 6 | Tailwind 样式被清除（PurgeCSS） | 生产构建后样式丢失 |
+| 7 | React 多实例冲突 | `Invalid hook call` |
+| 8 | 移动端 antd-mobile 组件样式不生效 | 组件渲染但无样式 |
+| 9 | 数据格式理解错误导致展示异常 | 页面显示 `[object Object]` |
+| 10 | workspace publish 环境变量缺失 | `OPENXIANGDA_ACCESS_TOKEN is not set` |
+
+---
+
+## 问题：antd/antd-mobile 弹层样式丢失
+
+**症状**：Select / Dropdown / Popup / Modal 等组件的弹出层没有样式，直接跑到屏幕外，或呈现为无样式的裸 HTML。
+
+**根因**：当页面启用了 Shadow DOM 样式隔离（`cssIsolation: "shadow"`）时，antd 组件的弹出层默认会渲染到 `document.body`，从而脱离 Shadow DOM 的样式作用域；即使未使用 Shadow DOM，如果没有正确配置弹层容器，antd-mobile 的 Popup 也可能因 namespace 未被继承而失去样式。
+
+**解决方案**：
+1. 推荐使用 CSS Namespace 隔离（`cssIsolation: "namespace"`）替代 Shadow DOM。
+2. 为 antd `ConfigProvider` 配置 `getPopupContainer` 指向页面根容器。
+3. 对于 antd-mobile，确保 `Popup` / `Modal` 的 `getContainer` 指向正确容器。
+4. 确保弹层的 `className` 中包含 namespace class（如 `sy-app-workspace`）。
+
+**示例**：
+```tsx
+import { useRef } from 'react';
+import { ConfigProvider } from 'antd';
+
+const rootRef = useRef<HTMLDivElement>(null);
+
+<div ref={rootRef} className="sy-app-workspace">
+  <ConfigProvider getPopupContainer={() => rootRef.current!}>
+    <App />
+  </ConfigProvider>
+</div>
+```
+
+**预防措施**：在 workspace 初始化阶段就统一约定弹层容器策略，避免后续逐个组件修复。
+
+---
+
+## 问题：SelectField options 为 undefined 导致 .map 报错
+
+**症状**：渲染 `SelectField` / `RadioField` / `CheckboxField` 时抛出 `Cannot read properties of undefined (reading 'map')`。
+
+**根因**：这些需要枚举值的字段组件在 schema 中未提供 `options` 属性，组件内部直接调用 `options.map(...)`。
+
+**解决方案**：
+- 确保所有选择类字段在 schema 中至少包含 `options: []`。
+- 使用 `createFormSchema` 工厂函数，它会自动为缺失的 options 字段补齐空数组。
+
+**预防措施**：
+```typescript
+// form-schema.ts 中的保护逻辑
+const NEEDS_OPTIONS = ['SelectField', 'RadioField', 'CheckboxField'];
+
+for (const field of schema.fields) {
+  if (NEEDS_OPTIONS.includes(field.componentName) && !Array.isArray(field.options)) {
+    field.options = [];
+  }
+}
+```
+
+---
+
+## 问题：ESM 模块动态导入路径错误
+
+**症状**：执行 `sync-schema` 等脚本时报 `ERR_UNSUPPORTED_ESM_URL_SCHEME` 或 `Cannot find module`。
+
+**根因**：Node.js 的 `import()` 在部分环境下（尤其是 Windows）不接受纯文件路径，必须使用 `file://` URL 形式。
+
+**解决方案**：
+```javascript
+import { pathToFileURL } from 'url';
+
+// 错误写法（可能在 Windows 下报错）
+const module = await import(tmpFile);
+
+// 正确写法
+const module = await import(pathToFileURL(tmpFile).href);
+```
+
+**预防措施**：所有动态 `import()` 文件路径统一通过 `pathToFileURL().href` 转换，CI 中加入 Windows 平台冒烟测试。
+
+---
+
+## 问题：Windows 环境 OSS 上传路径错误
+
+**症状**：发布完成后访问页面，CSS / JS 资源返回 404，浏览器 Network 面板中可见 URL 内出现反斜杠 `\`。
+
+**根因**：Windows 文件系统使用 `\` 作为路径分隔符，而 OSS 对象 key 必须使用 `/`，未做归一化时直接拼接路径会导致非法 key。
+
+**解决方案**：
+```javascript
+function toOssKeyPath(file) {
+  return String(file).replace(/\\/g, '/');
+}
+
+const ossKey = toOssKeyPath(path.relative(distDir, absFile));
+await ossClient.put(ossKey, absFile);
+```
+
+**预防措施**：在上传函数入口处统一调用 `toOssKeyPath`，禁止直接拼接原始路径。
+
+---
+
+## 问题：构建时表单 API 常量替换失败
+
+**症状**：生成的 `formApi.ts` 中，环境变量（如 `APP_ID`、`BASE_URL`）等常量值没有被正确替换为目标 profile 的真实值。
+
+**根因**：旧的替换正则只覆盖了简单字符串字面量，无法匹配对象字面量、函数调用、模板字符串等复杂初始化表达式。
+
+**解决方案**：使用更宽松的正则匹配 `=` 到 `;` 之间的任意表达式：
+```javascript
+const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const regex = new RegExp(
+  `((?:export\\s+)?const\\s+${escaped}\\s*=\\s*)([^;]+);`
+);
+source = source.replace(regex, (_, prefix) => `${prefix}${JSON.stringify(value)};`);
+```
+
+**预防措施**：替换后立即写一个 sanity check，比较替换前后的 AST 是否仅常量值发生变化。
+
+---
+
+## 问题：Tailwind 样式被清除（PurgeCSS 问题）
+
+**症状**：开发环境（`vite dev`）下页面样式正常，但 `vite build` 生产产物中部分组件样式丢失。
+
+**根因**：Tailwind v3+ 的 `content` 配置未包含来自 SDK / 组件库的源文件，组件库内使用的类名在编译期被 PurgeCSS 误删。
+
+**解决方案**：
+```javascript
+// tailwind.config.cjs
+module.exports = {
+  content: [
+    './src/**/*.{ts,tsx}',
+    './node_modules/openxiangda/packages/sdk/dist/**/*.{mjs,cjs}', // 关键：包含 SDK 分发文件
+  ],
+  presets: [require('openxiangda/tailwind-preset')],
+};
+```
+
+**预防措施**：每次新增第三方组件库时，同步将其分发产物路径加入 `content` 数组；将 `pnpm build` 纳入 CI，对比构建产物体积异常增减。
+
+---
+
+## 问题：React 多实例冲突
+
+**症状**：运行时抛出 `Invalid hook call. Hooks can only be called inside of the body of a function component.`，组件中所有 hooks 失效。
+
+**根因**：项目最终打包产物中存在多个 React 实例，通常是因为组件库与宿主项目各自引入了不同版本的 `react` / `react-dom`。
+
+**解决方案**：
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  resolve: {
+    dedupe: ['react', 'react-dom', 'antd'],
+  },
+});
+```
+
+**预防措施**：
+- 在 `package.json` 中将 `react` / `react-dom` 设为 SDK 的 `peerDependencies`。
+- 使用 `pnpm why react` 排查重复依赖。
+
+---
+
+## 问题：移动端 antd-mobile 组件样式不生效
+
+**症状**：antd-mobile 组件 DOM 已渲染，但样式全部丢失，呈现裸 HTML。
+
+**根因**：antd-mobile 使用 CSS-in-JS / 预编译样式，可能被 Tailwind 的 preflight 重置覆盖，或受 namespace 隔离影响。
+
+**解决方案**：
+1. 在 `vite.config.ts` 的 `optimizeDeps.include` 中显式添加 `antd-mobile`，避免运行时多次预构建。
+2. 调整 Tailwind preflight 策略，确保不会覆盖 antd-mobile 的基础样式（必要时关闭 preflight 或使用 `important` 选择器）。
+3. 确保 antd-mobile 组件渲染在 `sy-app-workspace` namespace 容器内，弹层 `getContainer` 指向该容器。
+
+**示例**：
+```typescript
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: {
+    include: ['antd-mobile', 'antd-mobile/es/locales/zh-CN'],
+  },
+});
+```
+
+**预防措施**：移动端项目模板中预置好 antd-mobile 的 vite 与 Tailwind 配置，禁止业务方随意修改 preflight。
+
+---
+
+## 问题：数据格式理解错误导致展示异常
+
+**症状**：页面显示 `[object Object]`、空白，或筛选条件无法命中数据。
+
+**根因**：AI 将平台返回的 `{label, value}` 结构字段当作纯字符串处理，直接渲染对象到 JSX。
+
+**解决方案**：参考 `platform-data-model.md`，选择类字段在平台中存储为对象（单选为对象，多选为对象数组），渲染时需取 `label` 字段：
+```tsx
+// 错误：直接展示对象
+<span>{record.department}</span>           // 显示 [object Object]
+
+// 正确：取 label
+<span>{record.department?.label}</span>
+
+// 多选字段
+<span>{record.tags?.map(t => t.label).join(', ')}</span>
+```
+
+**预防措施**：
+- 编辑器中为选择类字段统一定义 `OptionValue = { label: string; value: string }` 类型。
+- 列表 / 详情页渲染前，封装 `formatOption(value)` 工具函数。
+
+---
+
+## 问题：workspace publish 环境变量缺失
+
+**症状**：执行发布命令时报错 `OPENXIANGDA_ACCESS_TOKEN is not set` 或类似缺少配置项的错误。
+
+**根因**：没有通过 `openxiangda` CLI 触发发布，CLI 负责从安全存储读取 profile 配置并注入到子进程的环境变量中；直接运行 `pnpm` 脚本会绕过这一步骤。
+
+**解决方案**：
+- 始终通过 CLI 发布：
+  ```bash
+  openxiangda workspace publish --profile <profile-name>
+  ```
+- **不要**直接执行 `pnpm run publish:all` / `node scripts/publish.js`，这些命令缺少 token 注入。
+
+**预防措施**：
+- 在 workspace 的 `package.json` 中将真正的发布脚本设为内部脚本（前缀 `_`），README 与 SKILL 文档统一引导走 CLI 入口。
+- 必要时在脚本入口处增加守卫，检测到 `OPENXIANGDA_ACCESS_TOKEN` 缺失时输出明确指引：`请通过 openxiangda workspace publish 发布`。

package/openxiangda-skills/references/workflow-v3.md

@@ -0,0 +1,105 @@
+# Workflow V3 Reference
+
+Workflow definitions are JSON objects saved by `openxiangda workflow create`.
+
+Minimum shape:
+
+```json
+{
+  "version": "v3",
+  "nodes": [
+    { "id": "start", "type": "start", "data": { "label": "开始" } },
+    { "id": "approve", "type": "approval", "data": { "label": "审批" } },
+    { "id": "end", "type": "end", "data": { "label": "结束" } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "start", "target": "approve" },
+    { "id": "e2", "source": "approve", "target": "end" }
+  ],
+  "flowConfig": {}
+}
+```
+
+Rules:
+
+- `nodes` and `edges` must be arrays.
+- `version` must be `v3`.
+- Publishing requires one `start` node and at least one `end` node.
+- Each node needs `id`, `type`, and object `data`.
+- Edges must reference existing node IDs.
+- Keep live platform IDs out of the JSON when possible. Resolve `formUuid` and `workflowId` through CLI state.
+- JS_CODE V2 supports trusted Node execution. For AI/admin logic use `runtimeMode: "trusted_node"`.
+
+Supported node types:
+
+- `start`
+- `approval`
+- `condition`
+- `condition_branch`
+- `end`
+- `copy`
+- `js_code`
+- `branch`
+- `data_retrieve_single`
+- `data_retrieve_batch`
+- `data_create`
+- `data_update`
+- `loop_container`
+- `connector_call`
+- `callback_wait`
+- `work_notification`
+- `dingtalk_card`
+
+## JS_CODE V2
+
+Inline:
+
+```json
+{
+  "id": "calc",
+  "type": "js_code",
+  "data": {
+    "label": "计算",
+    "runtimeMode": "trusted_node",
+    "sourceType": "inline",
+    "code": "const crypto = require('crypto'); variables.hash = crypto.createHash('sha256').update('x').digest('hex'); return variables.hash;",
+    "timeout": 30000
+  }
+}
+```
+
+File snapshot:
+
+```json
+{
+  "id": "sync_customer",
+  "type": "js_code",
+  "data": {
+    "label": "同步客户",
+    "runtimeMode": "trusted_node",
+    "sourceType": "file_snapshot",
+    "scriptCode": "sync_customer",
+    "sourceFile": {
+      "localPath": "src/js-code-nodes/sync_customer/index.ts"
+    },
+    "timeout": 30000
+  }
+}
+```
+
+AI-authored JS_CODE source must be TypeScript under `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`. When validating or creating, the CLI runs `pnpm build-js-code --script <scriptCode>`, which runs TypeScript validation first, bundles to `dist/js-code-nodes/<scriptCode>/index.cjs`, uploads the bundle, and replaces `sourceFile.localPath` with immutable snapshot metadata. Scripts can export `export default async function (ctx) {}` or `module.exports = async (ctx) => {}` and call `ctx.platform.api` or global `platform.api`; the default API namespace is `/openxiangda-api/v1`.
+
+Field permission config lives in `flowConfig` by node ID:
+
+```json
+{
+  "flowConfig": {
+    "approve": [
+      { "fieldId": "amount", "fieldBehavior": "READONLY" },
+      { "fieldId": "remark", "fieldBehavior": "NORMAL" }
+    ]
+  }
+}
+```
+
+Allowed `fieldBehavior` values: `NORMAL`, `READONLY`, `HIDDEN`.

package/openxiangda-skills/references/workspace-state.md

@@ -0,0 +1,45 @@
+# Workspace State
+
+OpenXiangda project state lives in `.openxiangda/state.json`.
+
+Tokens never belong in the project. User tokens live in `~/.openxiangda/profiles.json`.
+
+## Shape
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "dev": {
+      "baseUrl": "https://dev-lowcode.example.com/service",
+      "appType": "APP_DEV",
+      "resources": {
+        "forms": {
+          "customer": {
+            "formUuid": "FORM_XXX"
+          }
+        },
+        "pages": {
+          "dashboard": {
+            "pageId": "PAGE_XXX",
+            "routeKey": "dashboard",
+            "legacyFormUuid": "FORM_LEGACY_PAGE"
+          }
+        },
+        "workflows": {},
+        "automations": {},
+        "menus": {}
+      }
+    }
+  }
+}
+```
+
+## Rules
+
+- Profile is the deployment boundary.
+- `baseUrl` is the backend API base. On standard private deployments it is `<origin>/service`; management pages use `/platform`, and app runtime pages use `/view`.
+- Local resource keys are logical codes.
+- Live IDs are nested under the profile that produced them.
+- A prod publish must not read dev IDs.
+- Before publishing to another platform, run `openxiangda workspace bind --profile <name> --app-type <APP_XXX>`.

package/openxiangda-skills/skills/openxiangda-app/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: openxiangda-app
+description: Manage OpenXiangda low-code apps, profiles, workspace initialization, workspace binding, app snapshots, menus, and profile-isolated resource state through the openxiangda CLI.
+---
+
+# OpenXiangda App
+
+Use this when the user needs to create, bind, inspect, or publish an app on a private OpenXiangda platform.
+
+## Required Context
+
+Always start from the current profile and workspace binding:
+
+```bash
+openxiangda env --profile <name>
+openxiangda auth status --profile <name>
+```
+
+If the workspace is not bound:
+
+```bash
+openxiangda app list --profile <name>
+openxiangda workspace bind --profile <name> --app-type APP_XXX
+```
+
+If there is no local app workspace yet:
+
+```bash
+openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXX
+cd ./my-app-workspace
+pnpm install
+```
+
+For menu work:
+
+```bash
+openxiangda menu list --profile <name>
+openxiangda menu create main --name "主菜单" --type nav --profile <name>
+openxiangda menu create customer-entry --name "客户信息" --type receipt --form-code customer --profile <name>
+```
+
+If the app does not exist:
+
+```bash
+openxiangda app create "应用名称" --profile <name>
+openxiangda workspace bind --profile <name> --app-type APP_XXX
+```
+
+## Rules
+
+- Never ask for AK/SK.
+- Always pass `--profile` for publish or cross-platform operations.
+- Use `openxiangda workspace init <dir>` before page/form work when the user starts from a new empty directory.
+- Store platform-specific IDs only in `.openxiangda/state.json`.
+- Use logical local codes for forms, pages, workflows, automations, and menus.
+- Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` before changing an existing app.
+
+## Resource State
+
+Read `../../references/workspace-state.md` when changing `.openxiangda/state.json`.
+
+Read `../../references/openxiangda-api.md` when exact endpoint fields are needed.
+
+Read `../../references/architecture-patterns.md` to understand the overall app structure (how forms, pages, menus, workflows, and permissions compose into an app, and the recommended `src/forms` / `src/pages` layout) before scaffolding or restructuring an app workspace.

package/openxiangda-skills/skills/openxiangda-core/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: openxiangda-core
+description: Core OpenXiangda CLI workflow for normal-user token login, platform profiles, workspace initialization, workspace binding, multi-platform publishing, and lightweight app inspection.
+---
+
+# OpenXiangda Core
+
+## Login
+
+Use ordinary platform login:
+
+```bash
+openxiangda login https://lowcode.example.com --profile dev
+```
+
+The CLI creates a one-time login session, opens the platform authorization page, polls the backend, and stores the returned `accessToken` and `refreshToken` in `~/.openxiangda/profiles.json` with file mode `0600`.
+
+Do not request or generate AK/SK credentials.
+
+## Private Routing
+
+OpenXiangda private deployments use fixed public paths:
+
+- `/service` for backend APIs.
+- `/platform` for platform management pages and login redirects.
+- `/view` for app runtime pages.
+
+The CLI profile stores the API base. If the user enters a root domain, `/platform` URL, or `/view` URL, normalize it to `<origin>/service` before calling OpenXiangda APIs. Never call `/openxiangda-api/v1` directly at the root domain.
+
+## Profiles
+
+```bash
+openxiangda platform add dev https://dev-lowcode.example.com
+openxiangda platform add prod https://lowcode.example.com/platform
+openxiangda platform list
+openxiangda platform use dev
+```
+
+Use `--profile` for every destructive or publishing action. Treat the profile as the deployment boundary.
+
+Run write commands sequentially in the same workspace because they update `.openxiangda/state.json`. Read-only commands such as list, pull, snapshot, and inspect may run in parallel.
+
+## Workspace State
+
+Create a workspace when the current project does not already contain a `sy-lowcode-app-workspace`:
+
+```bash
+openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_DEV
+cd ./my-app-workspace
+pnpm install
+openxiangda env --profile dev
+```
+
+If the workspace already exists, bind each platform to its own app, then publish from `sy-lowcode-app-workspace`:
+
+```bash
+openxiangda app list --profile dev
+openxiangda app create "测试应用" --profile dev
+openxiangda workspace bind --profile dev --app-type APP_DEV
+openxiangda workspace bind --profile prod --app-type APP_PROD
+cd /path/to/sy-lowcode-app-workspace
+openxiangda workspace publish --profile dev
+```
+
+Read-only diagnosis can use resource commands:
+
+```bash
+openxiangda form list --profile dev
+openxiangda form pull customer --profile dev
+openxiangda page list --profile dev
+openxiangda workflow list --form-code customer --profile dev
+openxiangda automation list --form-code customer --profile dev
+openxiangda permission role-list --profile dev
+openxiangda settings get customer --profile dev
+openxiangda inspect app --profile dev --json
+```
+
+`openxiangda form create`, `form publish`, and `page publish` are low-level repair commands. Do not use them as the normal AI page generation path.
+
+Project state is stored in `.openxiangda/state.json`:
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "dev": {
+      "baseUrl": "https://dev-lowcode.example.com/service",
+      "appType": "APP_DEV",
+      "resources": {
+        "forms": {},
+        "pages": {},
+        "workflows": {},
+        "automations": {},
+        "menus": {},
+        "roles": {},
+        "pagePermissionGroups": {},
+        "formPermissionGroups": {}
+      }
+    }
+  }
+}
+```
+
+The CLI reads `.openxiangda/state.json` from the current working directory. Run workspace commands from the workspace root unless the CLI has explicit parent-directory discovery in the current version.
+
+## Inspection
+
+Use snapshots to understand an app before editing:
+
+```bash
+openxiangda app snapshot APP_XXX --profile dev --json
+```
+
+The snapshot endpoint aggregates app metadata, forms, menus, code pages, release summaries, and permission hints using the logged-in user's permissions.
+
+## Publishing
+
+```bash
+openxiangda workspace publish --profile prod
+```
+
+The CLI checks that the target profile is logged in and bound to an app. It then runs the workspace publish script with these environment variables:
+
+- `OPENXIANGDA_PROFILE`
+- `OPENXIANGDA_BASE_URL`
+- `OPENXIANGDA_ACCESS_TOKEN`
+- `OPENXIANGDA_APP_TYPE`
+
+Publishing scripts must read these values instead of AK/SK.
+
+The publish script is responsible for:
+
+1. Scanning `src/forms/*/schema.ts` and `page.tsx` for normal and workflow form pages.
+2. Creating or binding platform form shells only as needed.
+3. Building form runtime, form bundles, and code page bundles.
+4. Uploading assets to OSS.
+5. Registering bundles through `/openxiangda-api/v1` with `OPENXIANGDA_ACCESS_TOKEN`.
+
+## References
+
+- `../../references/openxiangda-api.md` — exact endpoint contracts.
+- `../../references/workspace-state.md` — `.openxiangda/state.json` shape and profile-scoped resource maps.
+- `../../references/architecture-patterns.md` — overall architecture of an OpenXiangda app workspace (CRUD data flow, page/form layering, recommended directory organization). Read this when you need to understand how forms, pages, workflows, and platform state fit together end-to-end.

package/openxiangda-skills/skills/openxiangda-form/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: openxiangda-form
+description: Create, bind, generate, sync, and publish OpenXiangda normal form pages and workflow form pages through sy-lowcode-app-workspace bundles, profile state, and token-based workspace publish.
+---
+
+# OpenXiangda Form
+
+Use this when the user asks to create or update normal forms, workflow forms, form page source, form bundles, or form runtime publishing.
+
+## Required Workspace Flow
+
+```bash
+openxiangda env --profile <name>
+openxiangda form list --profile <name>
+cd /path/to/sy-lowcode-app-workspace
+```
+
+If the workspace does not exist yet, create it before writing form source:
+
+```bash
+openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXX
+cd ./my-app-workspace
+pnpm install
+```
+
+Create or edit workspace source:
+
+```text
+src/forms/<formCode>/
+├── schema.ts
+└── page.tsx
+```
+
+Then publish:
+
+```bash
+openxiangda workspace publish --profile <name>
+```
+
+The workspace publish script receives `OPENXIANGDA_BASE_URL`, `OPENXIANGDA_ACCESS_TOKEN`, and `OPENXIANGDA_APP_TYPE` from the CLI. It creates/binds the platform form shell only when needed, syncs form metadata, builds the React form page bundle, uploads assets, and registers the bundle.
+
+## Low-level Commands
+
+Use these only for diagnosis, binding existing resources, or repairing a broken publish state:
+
+```bash
+openxiangda form bind customer --form-uuid FORM_XXX --profile <name>
+openxiangda form pull customer --profile <name> --json
+openxiangda form create customer --name "客户信息" --profile <name>
+openxiangda form publish customer --bundle-url <url> --profile <name>
+```
+
+Do not use `openxiangda form create` as the normal way to generate a user-facing page. It creates the old platform form shell and will show the legacy default schema until a workspace bundle is published.
+
+## Workspace Form Rules
+
+Read these references only when writing or reviewing schema:
+
+- `../../references/forms/form-schema.md`
+- `../../references/forms/component-registry.md`
+- `../../references/forms/layout-and-rules.md`
+- `../../references/platform-data-model.md` — how each field type is persisted (JSONB, `{label, value}` for option fields, attachment shape). Consult before designing schema or wiring values.
+- `../../references/component-guide.md` — when to pick platform form components vs. custom widgets, and the option-component rules.
+
+## Rules
+
+- Prefer deterministic `formCode` as local key; bind live `formUuid` under the active profile.
+- For multi-platform publishing, create or bind the form separately for each profile.
+- Do not copy `formUuid` from dev to prod unless the target platform explicitly already uses that ID.
+- Keep `schema.ts` and `page.tsx` as the source for fields/layout/rules and presentation; generated build output is not the source of truth.
+- In `schema.ts`, import `defineFormSchema` from `openxiangda` and default-export the schema.
+- Put validation on field-level `rules`; never generate old top-level validation arrays under `schema.rules`. Top-level `rules` is only for `FormEffect[]` with `when` and `then`.
+- Always provide `options` for option components. `SelectField`, `MultiSelectField`, `RadioField`, `CheckboxField`, and `CascadeSelectField` must not be emitted with `options` undefined. See `../../references/component-guide.md` for the full list and `../../references/platform-data-model.md` for the `{label, value}` storage contract.
+- Workflow form pages use the same workspace form structure plus workflow v3 configuration; publish the form page bundle through workspace publish before treating it as complete.
+- Use `openxiangda form pull` or app snapshot before overwriting an existing form.
+- Before assuming a value shape (e.g. dates, attachments, member fields, option fields), verify against `../../references/platform-data-model.md` instead of guessing.