openxiangda 1.0.36 → 1.0.38

package/templates/sy-lowcode-app-workspace/.cursor/rules/openxiangda-resources.mdc

@@ -0,0 +1,28 @@
+---
+description: src/resources/** — Resource manifests, use logical codes only
+globs: src/resources/**/*
+alwaysApply: false
+---
+
+# OpenXiangda Resource Manifests
+
+Editing engineering-managed manifests under `src/resources/`. **All platform IDs are resolved by the CLI**; only logical `code` values go here.
+
+| Path | Skill |
+|---|---|
+| `connectors/<code>.json` | `openxiangda-page` |
+| `data-views/<code>.json` | `openxiangda-form` |
+| `notifications/<code>.json` | `openxiangda-page` / `-workflow-automation` |
+| `workflows/<code>/` | `openxiangda-workflow-automation` |
+| `automations/<code>/` | `openxiangda-workflow-automation` |
+| `roles/<code>.json` | `openxiangda-permission-settings` |
+| `permissions/page-groups/<code>.json` | `openxiangda-permission-settings` |
+| `permissions/form-groups/<formCode>/<code>.json` | `openxiangda-permission-settings` |
+| `settings/forms/<formCode>.json` | `openxiangda-permission-settings` |
+| `menus/<code>.json` | `openxiangda-app` |
+
+See `references/resource-manifest-cheatsheet.md` for copy-paste skeletons.
+
+Commands: `openxiangda resource validate|plan|publish|pull --profile <name>`.
+
+Forbidden: 把 `formUuid` / `pageId` / `workflowId` 等平台 ID 写进 manifest；把 API key / token / secret / authorization 写进 manifest；data view 用作单表 CRUD / linkedForm / 写回 / 强实时；page 源里 hardcode 通知或 connector URL。

package/templates/sy-lowcode-app-workspace/.cursor/rules/openxiangda-workflow-automation.mdc

@@ -0,0 +1,21 @@
+---
+description: src/{workflows,automations,js-code-nodes}/** — Use openxiangda-workflow-automation skill
+globs: src/{workflows,automations,js-code-nodes}/**/*
+alwaysApply: false
+---
+
+# OpenXiangda Workflow / Automation / JS_CODE
+
+Editing one of:
+- `src/workflows/<code>/workflow.ts`        # 代码优先工作流
+- `src/automations/<code>/index.ts`         # automation_code_ts (推荐)
+- `src/js-code-nodes/<code>/index.ts`       # JS_CODE V2 trusted_node
+
+Use the **`openxiangda-workflow-automation`** skill.
+
+Boundary: **大多数业务流转不是 workflow**。`pending → processing → resolved → closed` 用表单 `status` 字段 + 状态机 + automation。仅有真审批语义（审批人 / 任务 / 同意/驳回 / 节点权限 / 流程记录）才创建 workflow。
+
+JS_CODE 适用：跨表查询、批量更新、终止流程、平台 API、外部 HTTP。**不适用**：UI 交互、普通校验、展示逻辑。
+
+Build: `pnpm build-js-code --script <code>`（先 `tsc` 再打包）。
+Publish: `openxiangda workflow|automation validate|create|publish --profile <name>`。

package/templates/sy-lowcode-app-workspace/.cursor/rules/openxiangda.mdc

@@ -0,0 +1,47 @@
+---
+description: OpenXiangda workspace strong constraint — routing, commands, invariants, prohibitions
+alwaysApply: true
+---
+
+# OpenXiangda Workspace Rule
+
+This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. See [AGENTS.md](mdc:AGENTS.md) for full guidance.
+
+## Hard route — user intent → skill / command
+
+| User says | Skill | Command |
+|---|---|---|
+| publish / deploy / 发布 / 上线 / 部署 | `openxiangda-core` | `openxiangda workspace publish --profile <name>` (+ `--changed` / `--page` / `--form` / `--only`) |
+| create / scaffold app / 创建应用 / 初始化 | `openxiangda-app` | `openxiangda workspace init <dir> --profile <name> --app-name "..."` |
+| bind existing app / 绑定已有应用 | `openxiangda-app` | `openxiangda workspace bind --profile <name> --app-type APP_XXX` |
+| edit form / schema / 表单字段 / 表单页 | `openxiangda-form` | edit `src/forms/<code>/` → `workspace publish --form <code>` |
+| edit code page / portal / dashboard / 代码页 | `openxiangda-page` | edit `src/pages/<code>/` → `workspace publish --page <code>` |
+| approval workflow / 审批流程 / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow ...` |
+| automation / cron / 自动化 / 定时 | `openxiangda-workflow-automation` | `openxiangda automation ...` |
+| role / permission / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| diagnose / snapshot / 排查 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot APP_XXX --profile <name> --json` |
+| login / token / switch profile | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
+
+## Always
+
+- For routine edits, default to incremental publish: `workspace publish --profile <name> --changed --dry-run` then `--changed` or targeted `--page <code>` / `--form <code>`.
+- Confirm current profile before any write: `openxiangda env --profile <name>`.
+- `.openxiangda/state.json` is the authoritative profile → appType → resource-ID map; CLI maintains it, do not hand-edit.
+- User tokens live in `~/.openxiangda/profiles.json`; shared env in `~/.openxiangda/.env`.
+- Form fields need user-facing `placeholder`; use `SelectField` / `RadioField` for enums, `linkedForm` SelectField for cross-form sources.
+- Pages default to `cssIsolation: "none"` + native Tailwind utilities; formal entries must be app-shell.
+
+## Never
+
+- ❌ `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*` directly. They are guarded by `_guard:publish` and will fail-fast without `OPENXIANGDA_PROFILE`.
+- ❌ Ask for AK / SK / appKey / appSecret.
+- ❌ Search the platform for similar app names when `.openxiangda/state.json` has no binding.
+- ❌ Copy `formUuid` / `pageId` / `workflowId` / `automationId` across profiles.
+- ❌ Run a full publish for a single-file edit.
+- ❌ Use `openxiangda form create` / `form publish` / `page publish` as the normal page generation path.
+- ❌ Store tokens / AK / SK / third-party secrets in project files.
+- ❌ `npm publish` — this workspace is `"private": true`, not an npm package.
+
+## When unsure
+
+Read [AGENTS.md](mdc:AGENTS.md) and the global skill: `~/.qoder/skills/openxiangda/SKILL.md`.

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda-form.md

@@ -0,0 +1,34 @@
+---
+description: src/forms/** glob — 精准引导到 openxiangda-form skill
+glob: src/forms/**/*
+alwaysApply: false
+---
+
+# OpenXiangda Form Files
+
+You are editing files under `src/forms/<formCode>/`. Use the **`openxiangda-form`** skill.
+
+## Required structure
+
+```text
+src/forms/<formCode>/
+├── schema.ts   # defineFormSchema() default export — fields / options / rules / top-level FormEffect[]
+└── page.tsx    # presentation only
+```
+
+## Common pitfalls (high signal)
+
+- 选项字段（Select / MultiSelect / Radio / Checkbox / Cascade）必须有 `options`，不要给空。
+- 跨表数据 → `SelectField` + `optionSource.type: "linkedForm"`，**禁止** `AssociationFormField`。
+- 顶层 `schema.rules` 仅用于 `FormEffect[]`（`when` / `then`），**不要**写成校验数组；校验放字段 `rules`。
+- 平台系统字段（创建人 / 修改人 / 创建时间 / 修改时间 / 部门）由平台自动维护，**不要重复创建**。
+- 隐式权限键 / 派生键 → `behavior: "HIDDEN"` + `valueSync`。
+
+## Publish
+
+```bash
+openxiangda workspace publish --profile <name> --form <formCode> --dry-run
+openxiangda workspace publish --profile <name> --form <formCode>
+```
+
+不要用 `openxiangda form create` / `form publish` 作为日常路径（仅底层修复）。

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda-page.md

@@ -0,0 +1,37 @@
+---
+description: src/pages/** glob — 精准引导到 openxiangda-page skill
+glob: src/pages/**/*
+alwaysApply: false
+---
+
+# OpenXiangda Page Files
+
+You are editing files under `src/pages/<pageCode>/`. Use the **`openxiangda-page`** skill.
+
+## Required structure（复杂页面拆分）
+
+```text
+src/pages/<pageCode>/
+├── page.config.ts                    # entry / route / navigation
+├── page.tsx                          # 薄视图层
+├── domain/                           # 业务规则、状态机、查询构造器（可被 PC/移动复用）
+├── shared/{services,hooks}/          # 数据访问层、复用 hook
+├── components/                       # 页面内组件
+└── styles.css                        # 页面级样式
+```
+
+## Strong defaults
+
+- 正式入口（管理后台 / PC 门户 / 移动门户）必须 `entry: { mode: "app-shell", hidePlatformNav: true, defaultRoute: "<home>" }`。
+- 默认 `cssIsolation: "none"` + 原生 Tailwind utilities（`bg-white`, `border-slate-200`, `grid-cols-[240px_1fr]`），不要 `bg-card` / `text-muted-foreground` 这些未配置的 shadcn token。
+- 列表页：用 `DataManagementList` 模式 + 分页 + 结构化 `filterGroup`，**不要** `pageSize=10000` 然后前端过滤。
+- 外部接口：`src/resources/connectors/` + `sdk.connector.call()`；多表只读联表：`src/resources/data-views/` + `sdk.dataView.query()`；通知：`src/resources/notifications/` + `sdk.notification`。
+
+## Publish
+
+```bash
+openxiangda workspace publish --profile <name> --page <pageCode> --dry-run
+openxiangda workspace publish --profile <name> --page <pageCode>
+```
+
+不要用 `openxiangda page publish` 作为日常路径（仅底层修复）。

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda-resources.md

@@ -0,0 +1,46 @@
+---
+description: src/resources/** glob — 精准引导到 connector / data-view / notification / role / permission / settings 资源 manifest
+glob: src/resources/**/*
+alwaysApply: false
+---
+
+# OpenXiangda Resource Manifests
+
+You are editing engineering-managed resource manifests under `src/resources/`. **All平台资源 ID 由 CLI 解析**；本地只用逻辑 code。
+
+## 必看：复制即用速查
+
+`references/resource-manifest-cheatsheet.md`（installed at `~/.qoder/skills/openxiangda/references/resource-manifest-cheatsheet.md`）— connector / data-view / notification / workflow / automation / JS_CODE / role / page-group / form-group / settings / menu 骨架。
+
+## 文件夹与对应 skill
+
+| 路径 | 用途 | 主导 skill |
+|---|---|---|
+| `src/resources/connectors/<code>.json` | 第三方 / 自建系统 HTTP 连接器 | `openxiangda-page` |
+| `src/resources/data-views/<code>.json` | 多表只读联表（materialized view） | `openxiangda-form` |
+| `src/resources/notifications/<code>.json` | 通知模板 + typeConfigs | `openxiangda-page` / `-workflow-automation` |
+| `src/resources/workflows/<code>/{workflow.json,definition.v3.json,preview.json}` | 工作流 manifest | `openxiangda-workflow-automation` |
+| `src/resources/automations/<code>/{definition.code.json,preview.json}` | 自动化 manifest | `openxiangda-workflow-automation` |
+| `src/resources/roles/<code>.json` | 角色 | `openxiangda-permission-settings` |
+| `src/resources/permissions/page-groups/<code>.json` | 页面权限组 | `openxiangda-permission-settings` |
+| `src/resources/permissions/form-groups/<formCode>/<code>.json` | 表单权限组 | `openxiangda-permission-settings` |
+| `src/resources/settings/forms/<formCode>.json` | 表单设置 / 索引 / 数据管理页 / 公开访问 | `openxiangda-permission-settings` |
+| `src/resources/menus/<code>.json` | 菜单 | `openxiangda-app` |
+
+## 命令
+
+```bash
+openxiangda resource validate --profile <name>          # 静态校验
+openxiangda resource plan     --profile <name>          # diff 本地 vs. 平台
+openxiangda resource publish  --profile <name>          # upsert（默认不 prune）
+openxiangda resource publish  --profile <name> --prune  # 删除 manifest 未声明的平台资源（谨慎）
+openxiangda resource pull     --profile <name>          # 平台 → 本地
+```
+
+## 严禁
+
+- ❌ 把 `formUuid` / `pageId` / `workflowId` 等平台 ID 直接写进 manifest（CLI 解析逻辑 code）。
+- ❌ 把 API key / token / secret / password / authorization / headers / credential 写进 manifest（平台后台配置）。
+- ❌ data view 用作单表 CRUD、`linkedForm` 下拉、写回、强实时数据源。
+- ❌ 在 page 源里 hardcode `/api/notification-config/*` 或 `/connectors/actions/invoke`（用 `sdk.notification` / `sdk.connector`）。
+- ❌ 同时在 manifest 与平台后台编辑同一个资源（漂移源）。

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda-workflow-automation.md

@@ -0,0 +1,46 @@
+---
+description: src/{workflows,automations,js-code-nodes}/** glob — 精准引导到 openxiangda-workflow-automation skill
+glob: src/{workflows,automations,js-code-nodes}/**/*
+alwaysApply: false
+---
+
+# OpenXiangda Workflow / Automation / JS_CODE Files
+
+You are editing files under one of:
+
+- `src/workflows/<code>/workflow.ts`        # 代码优先工作流（推荐用于无需画布编辑的场景）
+- `src/automations/<code>/index.ts`         # 代码优先自动化（automation_code_ts，推荐）
+- `src/js-code-nodes/<code>/index.ts`       # JS_CODE V2 trusted_node 后端脚本
+
+Use the **`openxiangda-workflow-automation`** skill.
+
+## Boundary — workflow vs. status field
+
+**大多数业务流转不是工作流。** `pending → processing → resolved → closed` 用表单 + `status` 字段 + 状态机 + automation/JS_CODE。
+仅当存在**真正的审批语义**（审批人 / 审批任务 / 同意/驳回 / 意见 / 节点字段权限 / 流程记录 / 节点副作用）时创建 workflow。
+
+## JS_CODE 适用与不适用
+
+- ✅ 跨表查询、批量更新、终止流程、平台 API、外部 HTTP、复杂编排。
+- ✅ `ctx.logger.debug/info/warn/error(message, data?)` 在每个关键步骤埋点。
+- ❌ 简单 UI 交互、普通表单校验、纯展示逻辑 → 应在 React 代码页里。
+
+## 构建与发布
+
+```bash
+# JS_CODE V2 本地构建
+pnpm build-js-code --script <scriptCode>
+
+# workflow / automation 校验 + 发布
+openxiangda workflow  validate / create / publish --profile <name>
+openxiangda automation validate / create / publish / enable --profile <name>
+
+# 排查
+openxiangda automation executions <code> --profile <name>
+openxiangda automation logs <instanceId> --profile <name>
+openxiangda automation diagnose <code> --profile <name>
+```
+
+不要把 `workflowId` / `automationId` 跨 profile 复制；每个 profile 独立维护。
+
+详见 `references/automation-v3.md` / `workflow-v3.md` / `resource-manifest-cheatsheet.md`。

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda.md

@@ -0,0 +1,47 @@
+---
+description: OpenXiangda 工作区强约束 — 路由、命令、不变量、禁令
+alwaysApply: true
+---
+
+# OpenXiangda Workspace Rule
+
+This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. Read [AGENTS.md](AGENTS.md) for the full guidance. The summary below is auto-injected into every Qoder turn.
+
+## Hard route — 用户意图 → skill / 命令
+
+| 用户说 | 必用 skill | 必用命令 |
+|---|---|---|
+| 发布 / 上线 / 部署 / publish / deploy | `openxiangda-core` | `openxiangda workspace publish --profile <name>` (+`--changed` / `--page` / `--form` / `--only`) |
+| 创建 / 初始化应用 | `openxiangda-app` | `openxiangda workspace init <dir> --profile <name> --app-name "..."` |
+| 绑定已有应用 | `openxiangda-app` | `openxiangda workspace bind --profile <name> --app-type APP_XXX` |
+| 改表单字段 / schema / 表单页 | `openxiangda-form` | 编辑 `src/forms/<code>/` → `workspace publish --form <code>` |
+| 改代码页 / portal / dashboard | `openxiangda-page` | 编辑 `src/pages/<code>/` → `workspace publish --page <code>` |
+| 审批流程 / workflow / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow ...` |
+| 自动化 / 定时 / 提交触发 | `openxiangda-workflow-automation` | `openxiangda automation ...` |
+| 角色 / 权限 / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| 排查 / 快照 / 对比 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot APP_XXX --profile <name> --json` |
+| 登录 / token / 切平台 | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
+
+## Always
+
+- 单文件改动默认增量发布：先 `workspace publish --profile <name> --changed --dry-run`，再 `--changed` 或 `--page <code>` / `--form <code>`。
+- 任何写操作前确认当前 profile：`openxiangda env --profile <name>`。
+- `.openxiangda/state.json` 是 profile 到 appType / 资源 ID 的权威映射，由 CLI 维护，不要手改。
+- 用户 token 在 `~/.openxiangda/profiles.json`；共享 env 在 `~/.openxiangda/.env`。
+- 表单字段必须有 user-facing `placeholder`；选项使用 `SelectField` / `RadioField`，跨表用 `linkedForm` SelectField。
+- 页面默认 `cssIsolation: "none"` + 原生 Tailwind utilities；正式入口必须是 app-shell。
+
+## Never
+
+- ❌ `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*` 直接调用。它们由 `_guard:publish` 拦截，缺少 `OPENXIANGDA_PROFILE` 时会 fail-fast。
+- ❌ 询问 AK / SK / appKey / appSecret。
+- ❌ 在没有本地 `.openxiangda/state.json` 绑定时，去平台搜索同名应用"复用"。
+- ❌ 把 `formUuid` / `pageId` / `workflowId` / `automationId` 从 dev 复制到 prod。
+- ❌ 改一处就全量发布。
+- ❌ `openxiangda form create` / `form publish` / `page publish` 当作页面生成方式（仅底层修复）。
+- ❌ 把 token / AK / SK / 第三方密钥写进项目文件。
+- ❌ `npm publish` — 本工作区 `"private": true`，不发 npm 包。
+
+## When unsure
+
+读 [AGENTS.md](AGENTS.md) 与全局 skill：`~/.qoder/skills/openxiangda/SKILL.md`。

package/templates/sy-lowcode-app-workspace/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md — OpenXiangda 工作区 AI 强约束
+
+> 任何 AI（Qoder / Claude / Codex / Cursor / Copilot 等）在本工作区操作前 **必须先读完本文件**。
+> 这是 `sy-lowcode-app-workspace`，由 `openxiangda` CLI 统一管理；普通 npm 习惯不适用于此工作区的发布与生命周期操作。
+
+## 一句话原则
+
+**所有"发布 / 上线 / 部署 / publish / deploy / ship / release"请求，唯一正确入口是 `openxiangda workspace publish --profile <name>`，不要直接 `pnpm publish:all`。**
+
+工作区内的 npm scripts（`publish:all` / `publish:oss` / `register`）已加 `_guard:publish` 守卫；缺少 `OPENXIANGDA_PROFILE` 环境变量时会立即 fail，提示重新走 CLI 入口。
+
+## 路由表 — 用户意图 → 命令 / skill
+
+| 用户说（中 / 英） | 用 skill | 第一条命令 |
+|---|---|---|
+| 发布 / 上线 / 部署 / publish / deploy | `openxiangda-core` | `openxiangda workspace publish --profile <name> --changed --dry-run` |
+| 只发布改动 / 增量 / 单页 / 单表 | `openxiangda-core` | `... --changed` / `--page <code>` / `--form <code>` / `--only pages/a,forms/b` |
+| 创建应用 / 新建 app / 初始化工作区 | `openxiangda-app` | `openxiangda workspace init <dir> --profile <name> --app-name "..."` |
+| 绑定已有应用 | `openxiangda-app` | `openxiangda workspace bind --profile <name> --app-type APP_XXX` |
+| 创建 / 改表单字段、schema、表单页 | `openxiangda-form` | 编辑 `src/forms/<code>/{schema.ts,page.tsx}` → `workspace publish --form <code>` |
+| 创建 / 改自定义代码页、portal、看板 | `openxiangda-page` | 编辑 `src/pages/<code>/` → `workspace publish --page <code>` |
+| 审批流程 / 流程节点 / 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` |
+| 登录 / 切平台 / token / whoami | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
+| 多表只读联表查询 / 报表数据源 | `openxiangda-form`（data view） | 在 `src/resources/data-views/<code>.json` 声明 → `resource publish` |
+| 调外部 / 第三方 API / 钉钉 / 自建系统 | `openxiangda-page`（connector） | 在 `src/resources/connectors/<code>.json` 声明 → `sdk.connector.invoke()` |
+
+## 必须遵守
+
+- ✅ 先 preflight：`openxiangda env --profile <name>` + `openxiangda auth status --profile <name>` + `openxiangda update check --json`。
+- ✅ 单文件改动默认增量发布：`workspace publish --profile <name> --changed --dry-run` → `--changed` / `--page` / `--form`。
+- ✅ 用户 token 在 `~/.openxiangda/profiles.json`；项目 state 在 `.openxiangda/state.json`（只存 ID）。
+- ✅ 共享环境（`APP_OSS_*`、反馈机器人等）在 `~/.openxiangda/.env`，项目 `.env` 仅做 per-workspace override。
+- ✅ 多 profile（dev / prod / ...）资源 ID 互不复用；每个 profile 的 `appType` / `formUuid` / `pageId` / `workflowId` / `automationId` 独立维护。
+- ✅ 改已有应用前先 `openxiangda app snapshot APP_XXX --profile <name> --json`。
+
+## 严禁
+
+- ❌ 直接 `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*`。它们是工作区内部脚本，不会注入 `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE`，发到错的环境也无人提醒。
+- ❌ 询问 AK / SK / appKey / appSecret。整个流程基于普通用户登录 token。
+- ❌ 在没有本地 `.openxiangda/state.json` 绑定时，去平台搜索同名应用尝试"复用"。空目录 / 无绑定 → 直接 `workspace init --app-name` 创建新应用。
+- ❌ 把 `openxiangda form create` / `form publish` / `page publish` 当作日常页面生成方式。它们仅作底层修复 / 诊断。
+- ❌ 改一个文件就 `workspace publish` 全量。
+- ❌ 把 token、AK、SK、第三方密钥写进项目文件。
+- ❌ `npm publish` —— 这个工作区是 `"private": true` 的应用工作区，不是要发到 npm 的 package。
+
+## 表单 / 页面写作约束（高频踩坑）
+
+- 表单字段：可见字段必须有用户能看懂的 `placeholder`；`tips` 只用于特殊约束。
+- 表单选项：用 `SelectField` / `RadioField` 表枚举；跨表数据用 `SelectField` + `optionSource.type: "linkedForm"`（数据量大时加 `remoteSearch: true` + `searchFieldId`）。**禁止**新建 `AssociationFormField`。
+- 权限隐式键、计算字段、同步字段：在 schema 中保留 `behavior: "HIDDEN"`，由可见字段通过 `valueSync` 派生，不要让用户填裸 ID。
+- 页面默认 `cssIsolation: "none"` + 原生 Tailwind utilities（`bg-white`、`border-slate-200`、`grid-cols-[240px_1fr]` 等），不要用 `bg-card` / `text-muted-foreground` 这类未配置的 shadcn token。
+- 列表页用 `DataManagementList` 模式 + 分页 + 结构化 `filterGroup`，不要 `pageSize=10000` 然后前端过滤。
+- 正式入口（管理后台 / PC 门户 / 移动门户）必须是 app-shell：`page.config.ts` 里 `entry: { mode: "app-shell", hidePlatformNav: true, defaultRoute: "<home>" }`。
+- 对外接口走 `src/resources/connectors/`；多表只读联表走 `src/resources/data-views/`；通知模板走 `src/resources/notifications/`。
+
+## 工作区结构速查
+
+```text
+sy-lowcode-app-workspace/
+├── AGENTS.md                        # 本文件
+├── .qoder/rules/openxiangda.md      # Qoder always-on 项目规则
+├── .cursor/rules/openxiangda.mdc    # Cursor always-on 项目规则
+├── .openxiangda/state.json          # profile → appType → 资源 ID 的权威映射（CLI 维护）
+├── app-workspace.config.ts
+├── package.json                     # publish:all/publish:oss/register 都被 _guard:publish 守卫
+├── src/
+│   ├── forms/<formCode>/{schema.ts,page.tsx}    # 表单页源（openxiangda-form）
+│   ├── pages/<pageCode>/                         # 自定义代码页源（openxiangda-page）
+│   ├── workflows/<code>/workflow.ts              # 代码优先工作流（openxiangda-workflow-automation）
+│   ├── automations/<code>/index.ts               # 代码优先自动化
+│   ├── js-code-nodes/<code>/index.ts             # JS_CODE V2 trusted_node TS 源
+│   └── resources/                                 # data-views / connectors / notifications / roles / ...
+└── examples/best-practices/                       # 仅参考；不发布
+```
+
+## 还想看更细的
+
+- 全局 skill：`~/.qoder/skills/openxiangda/SKILL.md`（root 决策卡）+ 7 个子 skill。
+- 资源 / 连接器 manifest：`docs/openxiangda-resources-and-connectors.md`（来自 openxiangda 仓库）。
+- 平台数据模型：`references/platform-data-model.md`（option `{label, value}`、附件、成员字段等持久化形态）。
+- 排错清单：`references/troubleshooting.md`。
+
+## 升级现有工作区
+
+如果这份文件是后加上来的，请确认下面三件事：
+
+1. `package.json` 的 `publish:all` / `publish:oss` / `register` 已加上 `pnpm _guard:publish && ...` 前缀。
+2. `.qoder/rules/openxiangda.md` 与 `.cursor/rules/openxiangda.mdc` 都存在。
+3. `openxiangda update check --json` 显示已是最新，并跑过 `openxiangda skill install --force`。

package/templates/sy-lowcode-app-workspace/package.json

@@ -14,11 +14,18 @@
     "typecheck:js-code": "tsc -p tsconfig.js-code-nodes.json --noEmit",
     "examples:check": "tsc -p tsconfig.examples.json --noEmit",
     "sync-schema": "lowcode-workspace sync-schema",
+    "_guard:publish": "node scripts/guard-publish.mjs",
+    "prepublish:oss": "pnpm _guard:publish",
     "publish:oss": "lowcode-workspace publish-oss",
+    "preregister": "pnpm _guard:publish",
     "register": "lowcode-workspace register",
+    "preregister-bundle": "pnpm _guard:publish",
     "register-bundle": "lowcode-workspace register",
+    "prepublish:all": "pnpm _guard:publish",
     "publish:all": "lowcode-workspace publish-all",
+    "prepublish:changed": "pnpm _guard:publish",
     "publish:changed": "lowcode-workspace publish-all --changed",
+    "preopenxiangda:publish": "pnpm _guard:publish",
     "openxiangda:publish": "lowcode-workspace publish-all",
     "ai:update": "pnpm dlx openxiangda@latest lowcode-workspace update --channel latest",
     "ai:migrate": "pnpm dlx openxiangda@latest lowcode-workspace migrate",

package/templates/sy-lowcode-app-workspace/scripts/guard-publish.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// _guard:publish 守卫：拦截直接调用 publish:all / publish:oss / register 等内部 npm script 的尝试。
+// 仅当通过 `openxiangda workspace publish --profile <name>` 入口发布时，CLI 会注入
+// OPENXIANGDA_PROFILE / OPENXIANGDA_BASE_URL / OPENXIANGDA_ACCESS_TOKEN / OPENXIANGDA_APP_TYPE
+// 等环境变量；本守卫据此放行内部脚本，否则 fail-fast 并提示正确入口。
+
+if (!process.env.OPENXIANGDA_PROFILE) {
+  const lines = [
+    '',
+    '❌ 错误：请使用 openxiangda workspace publish --profile <name>',
+    '',
+    '此 npm script（publish:all / publish:oss / register / publish:changed / openxiangda:publish 等）',
+    '是工作区内部实现，直接调用会缺少 token / profile / appType / OSS 密钥的注入，',
+    '可能发到错误的环境，或彻底发不出去。',
+    '',
+    '正确入口：',
+    '  openxiangda workspace publish --profile <name>            # 全量',
+    '  openxiangda workspace publish --profile <name> --changed  # 增量（推荐）',
+    '  openxiangda workspace publish --profile <name> --page X   # 单页',
+    '  openxiangda workspace publish --profile <name> --form Y   # 单表',
+    '',
+    '更多说明详见工作区根目录的 AGENTS.md。',
+    '',
+  ];
+  for (const line of lines) {
+    console.error(line);
+  }
+  process.exit(1);
+}