openxiangda 1.0.36 → 1.0.38

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -0,0 +1,348 @@
+# Resource Manifest Cheatsheet
+
+> 1-2 屏速查：`src/resources/` 下各类型 manifest 的最小可用模板与对应运行时调用方式。
+> 这里只放"复制即用"的骨架；字段语义详见对应的 reference 文档。
+
+## 通用约定
+
+- **本地用逻辑 code**：所有 manifest 用稳定的 `formCode` / `pageCode` / `workflowCode` / `automationCode` / `connectorCode` / `dataViewCode` / `roleCode` / `notificationType`。
+- **平台 ID 由 CLI 解析**：`openxiangda resource publish --profile <name>` 把 code 解析成当前 profile 的真实 ID 并写回 `.openxiangda/state.json`。
+- **永远不写密钥**：第三方 API key、token、secret、password、authorization、headers 等绝不出现在 `src/resources/`，平台管理员在后台配置。
+- **多 profile 不共享 ID**：`dev` / `prod` 各自维护一份资源 ID 映射，复制 manifest 即可复用，不要复制平台 ID。
+
+## 命令
+
+```bash
+openxiangda resource validate --profile <name>          # 静态校验所有 manifest
+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>          # 拉取平台资源回写到本地（用于初次同步）
+```
+
+## 1. Connector — `src/resources/connectors/<code>.json`
+
+```json
+{
+  "code": "crm",
+  "name": "CRM Service",
+  "url": "https://crm.internal.example.com/api",
+  "authType": "apiKey",
+  "authConfig": {
+    "apiKey": { "key": "X-API-Key", "value": "internal-secret", "in": "header" }
+  },
+  "userContext": {
+    "enabled": true,
+    "inject": [
+      { "target": "header", "key": "X-User-Id", "value": "userId" },
+      { "target": "body",   "key": "operator", "value": "user" }
+    ]
+  },
+  "apis": [
+    {
+      "code": "getCustomer",
+      "name": "Get Customer",
+      "method": "POST",
+      "path": "/customers/search",
+      "requestBodyType": "json",
+      "responseType": "json"
+    }
+  ]
+}
+```
+
+页面调用：
+
+```ts
+const data = await sdk.connector.call("crm.getCustomer", { body: { keyword } });
+```
+
+不要把 `authConfig` 里的真实 secret 写进 manifest；用 placeholder，由平台管理员在后台覆盖。完整字段见 [`connector-resources.md`](connector-resources.md)。
+
+## 2. Data View — `src/resources/data-views/<code>.json`
+
+```json
+{
+  "code": "ticket_with_customer",
+  "name": "Ticket With Customer",
+  "base": { "formCode": "service_ticket", "alias": "ticket" },
+  "joins": [
+    {
+      "type": "left",
+      "formCode": "customer",
+      "alias": "customer",
+      "on": [
+        { "left": "ticket.customer.value", "op": "=", "right": "customer.form_instance_id" }
+      ]
+    }
+  ],
+  "select": [
+    { "field": "ticket.form_instance_id", "as": "ticketId" },
+    { "field": "ticket.title",            "as": "ticketTitle" },
+    { "field": "ticket.status.label",     "as": "statusLabel" },
+    { "field": "ticket.status.value",     "as": "statusValue" },
+    { "field": "customer.name",           "as": "customerName" }
+  ],
+  "indexes": [{ "fields": ["ticketId"], "unique": true }],
+  "refresh": { "mode": "scheduled", "cron": "0 */10 * * * *" },
+  "permissionGroups": [
+    { "code": "ticket_query", "name": "Ticket Query", "roles": ["manager"], "operations": ["query"] }
+  ]
+}
+```
+
+页面调用：
+
+```ts
+const list = await sdk.dataView.query("ticket_with_customer", {
+  filters: [{ field: "statusValue", op: "in", values: ["open", "processing"] }],
+  order: [{ field: "ticketId", direction: "desc" }],
+  page: { current: 1, size: 20 },
+});
+```
+
+适用：跨表只读联表 / 报表 / 大列表性能优化。**不适用**：单表 CRUD、`linkedForm` 下拉、强实时、写回。完整规则见 [`data-views.md`](data-views.md)。
+
+## 3. Notification — `src/resources/notifications/<code>.json`
+
+```json
+{
+  "templates": [
+    {
+      "code": "reservation_reminder",
+      "name": "预约提醒",
+      "content": "{{title}}",
+      "variables": ["title", "instrumentName", "startTime"],
+      "channelsConfig": {
+        "inapp":    { "enabled": true, "content": "{{instrumentName}} 将于 {{startTime}} 开始" },
+        "dingding": { "enabled": true, "content": "{{title}}" }
+      }
+    }
+  ],
+  "typeConfigs": [
+    {
+      "notificationType": "reservation_reminder",
+      "templateCode": "reservation_reminder",
+      "enabled": true,
+      "priority": 0
+    }
+  ]
+}
+```
+
+页面调用：
+
+```ts
+await sdk.notification.sendByType({
+  notificationType: "reservation_reminder",
+  recipientId: userId,
+  payload: { title: "预约提醒", instrumentName, startTime },
+});
+```
+
+JS_CODE 调用：`ctx.notification.sendByType({ ... })`。允许的 channels：`inapp` / `email` / `dingding` / `wechat` / `thirdparty_todo`。完整规则见 [`notifications.md`](notifications.md)。
+
+## 4. Workflow — `src/resources/workflows/<code>/workflow.json`（manifest）+ `src/workflows/<code>/workflow.ts`（代码优先）
+
+```jsonc
+// src/resources/workflows/customer_approval/workflow.json
+{
+  "code": "customer_approval",
+  "formCode": "customer",
+  "kind": "workflow_v3",
+  "definitionFile": "definition.v3.json",
+  "previewFile": "preview.json"
+}
+```
+
+代码优先（推荐）：
+
+```ts
+// src/workflows/customer_approval/workflow.ts
+import { defineWorkflow } from "openxiangda/workflow";
+
+export default defineWorkflow({
+  name: "客户审批",
+  trigger: { type: "form_submit", formCode: "customer" },
+  nodes: [
+    /* approval / copy / branch / js_code 节点 */
+  ],
+});
+```
+
+CLI 编译为 `definition.v3.json` + `preview.json`，平台运行时仍走标准工作流引擎。完整规则见 [`workflow-v3.md`](workflow-v3.md)。
+
+## 5. Automation — `src/resources/automations/<code>/{definition.code.json,preview.json}` + `src/automations/<code>/index.ts`
+
+```jsonc
+// src/resources/automations/notify_on_submit/definition.code.json
+{
+  "code": "notify_on_submit",
+  "name": "提交后通知",
+  "kind": "automation_code_ts",
+  "trigger": {
+    "version": 2,
+    "mode": "event",
+    "event": { "source": "form_data", "action": "submitted" },
+    "filters": { "formCode": "customer" }
+  },
+  "sourceFile": { "localPath": "src/automations/notify_on_submit/index.ts" },
+  "previewFile": "preview.json",
+  "timeout": 30000
+}
+```
+
+```ts
+// src/automations/notify_on_submit/index.ts
+export default async function (ctx) {
+  ctx.logger.info("automation start", { formCode: ctx.formData.current.formCode });
+  await ctx.notification.sendByType({
+    notificationType: "submission_notice",
+    recipientId: ctx.operator.userId,
+    payload: { /* ... */ },
+  });
+}
+```
+
+`trigger_v2` 事件源：`form_data` / `form_field` / `workflow_task` / `workflow_process` / `mode: "scheduled"`（fixed_time / form_date_field）。完整规则见 [`automation-v3.md`](automation-v3.md)。
+
+## 6. JS_CODE V2 — `src/js-code-nodes/<scriptCode>/index.ts`
+
+```ts
+export default async function (ctx) {
+  const { formData, operator, methods, notification, platform, utils, console } = ctx;
+  const result = await methods.queryManyData({
+    formCode: "customer",
+    formUuid: ctx.app.formUuids.customer,
+    searchCondition: [/* 查询条件 */],
+  });
+  return { count: result.length };
+}
+```
+
+工作流 / 自动化 v3 JSON 节点引用：
+
+```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
+  }
+}
+```
+
+构建：`pnpm build-js-code --script sync_customer`（先 `tsc` 再打包到 `dist/js-code-nodes/<code>/index.cjs`）。CLI validate/create/publish 时会上传快照、用 `{ bucketName, objectName, sha256 }` 替换 `sourceFile.localPath`。
+
+## 7. Role — `src/resources/roles/<code>.json`
+
+```json
+{
+  "code": "sales",
+  "name": "销售"
+}
+```
+
+## 8. Page Permission Group — `src/resources/permissions/page-groups/<code>.json`
+
+```json
+{
+  "code": "sales_pages",
+  "name": "销售页面",
+  "roles": ["sales"],
+  "formCodes": ["customer", "orders"],
+  "pageCodes": ["dashboard"]
+}
+```
+
+`formCodes` / `pageCodes` / `menuCodes` 留空表示对匹配角色全部可见。
+
+## 9. Form Permission Group — `src/resources/permissions/form-groups/<formCode>/<groupCode>.json`
+
+```json
+{
+  "code": "sales_view",
+  "name": "销售查看",
+  "type": "view",
+  "roles": ["sales"],
+  "operations": ["view"],
+  "dataScope": {
+    "type": "expression",
+    "match": "all",
+    "conditions": [
+      { "field": "ownerScopeKey", "op": "=", "valueRef": "currentUser.id" }
+    ]
+  },
+  "fieldPermissions": {
+    "internalNote": "hidden",
+    "amount": "readonly"
+  }
+}
+```
+
+## 10. Form Settings — `src/resources/settings/forms/<formCode>.json`
+
+```json
+{
+  "code": "customer",
+  "settings": {
+    "submitButtonText": "提交",
+    "successMessage": "提交成功"
+  },
+  "indexes": [
+    { "fields": ["customerCode"], "unique": true },
+    { "fields": ["status", "ownerDept"] }
+  ],
+  "dataManagement": { "enabled": true, "default": "list" },
+  "publicAccess": { "enabled": false }
+}
+```
+
+## 11. Menu — `src/resources/menus/<code>.json`
+
+```json
+{
+  "code": "main",
+  "name": "主菜单",
+  "type": "nav",
+  "children": [
+    { "code": "customer-entry", "name": "客户信息", "type": "receipt", "formCode": "customer" },
+    { "code": "orders-entry",   "name": "订单",     "type": "receipt", "formCode": "orders"   },
+    { "code": "dashboard-entry","name": "驾驶舱",   "type": "page",    "pageCode": "dashboard" }
+  ]
+}
+```
+
+## 选型决策树
+
+```text
+需要展示数据？
+├─ 单表 CRUD     → 表单页 + DataManagementList（不要 data view）
+├─ 多表只读联表  → src/resources/data-views/
+├─ 表单字段下拉  → SelectField + optionSource.type: "linkedForm"（不要 data view）
+└─ 大屏 / 报表    → 原生报表 → ECharts page
+
+需要后端逻辑？
+├─ 真有审批      → workflow（src/workflows/<code>/workflow.ts）
+├─ 状态流转      → 表单 status 字段 + 状态机 + automation
+├─ 提交/字段触发 → automation（trigger_v2 + src/automations/<code>/index.ts）
+├─ 定时任务      → automation（mode: "scheduled"）
+└─ 复杂后端逻辑  → JS_CODE V2 trusted_node（src/js-code-nodes/<code>/index.ts）
+
+需要外部数据？
+├─ 第三方 HTTP    → src/resources/connectors/ + sdk.connector.call
+└─ 钉钉 / 飞书等  → 同上，平台后端配置 OAuth/AK，前端只引用 connector code
+```
+
+## 常见错误
+
+- ❌ 把 `formUuid` / `pageId` 等平台 ID 写进 manifest。**用 code，CLI 自动解析。**
+- ❌ 把 API key、token、密码写进 manifest。**用占位符，平台后台填真实值。**
+- ❌ 同时在 manifest 与平台后台编辑同一个资源（漂移源）。**统一以 manifest 为单一来源**，需要看平台版本就 `resource pull`。
+- ❌ 用 data view 代替 `linkedForm` 下拉、单表 CRUD 或写回。**data view 是只读 + 延迟刷新。**
+- ❌ 在 page 源码里 hardcode `/api/notification-config/*` 或 `/connectors/actions/invoke`。**用 `sdk.notification` / `sdk.connector`。**

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

@@ -1,11 +1,27 @@
 ---
 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.
+description: Manage OpenXiangda low-code apps and workspaces — create / scaffold / bind / inspect / publish apps, manage menus / nav / 导航 / 菜单, app snapshots, and the profile-isolated `.openxiangda/state.json` resource map. Trigger on 创建应用 / 新建 app / scaffold app / 初始化工作区 / workspace init / workspace bind / appType / APP_XXX / app snapshot / 应用快照 / 菜单 / menu / nav, or when the user starts work in an empty folder that should become a sy-lowcode-app-workspace.
 ---
 
 # OpenXiangda App
 
-Use this when the user needs to create, bind, inspect, or publish an app on a private OpenXiangda platform.
+## When to use this skill
+
+- User wants to **create / scaffold a new app** or initialize a `sy-lowcode-app-workspace`.
+- User wants to **bind** the workspace to an existing platform app (`APP_XXX`) for one profile.
+- User asks about **menus / navigation / app snapshot / appType / .openxiangda/state.json shape**.
+- Before scaffolding a real business app: read the architecture-pattern decision via `references/best-practices.md`.
+
+## Decision card — new app vs. bind existing
+
+| Situation | Action |
+|---|---|
+| Empty folder, no `.openxiangda/state.json`, user did NOT mention an `appType` | `openxiangda workspace init <dir> --profile <name> --app-name "..."` (creates a NEW app) |
+| User explicitly provides `APP_XXX` or asks to reuse an existing app | `workspace init <dir> --profile <name> --app-type APP_XXX` |
+| Existing workspace, no binding for the target profile | `openxiangda workspace bind --profile <name> --app-type APP_XXX` |
+| Workspace already bound for the target profile | use it; never re-bind silently |
+
+**Never** search the platform for similar app names to "reuse" — local `.openxiangda/state.json` is authoritative.
 
 ## Required Context
 

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

@@ -1,10 +1,46 @@
 ---
 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.
+description: Core OpenXiangda CLI workflow — normal-user token login, platform profiles (dev / prod / staging), workspace init / bind / publish, multi-platform release, environment / version / token diagnostics. Trigger on 发布 / 上线 / 部署 / publish / deploy / ship / release, 登录 / login / 切换平台 / switch profile / token / whoami / auth, `openxiangda env` / `auth status` / `update check`, `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE`, or any release operation that must inject the profile token into a sy-lowcode-app-workspace publish.
 ---
 
 # OpenXiangda Core
 
+## When to use this skill
+
+- User wants to **publish / deploy / release / 发布 / 上线 / 部署** anything from a `sy-lowcode-app-workspace`.
+- User asks about **login / profile / token / whoami / 切平台 / 多环境**.
+- User runs into **CLI version drift, skill mismatch, missing OSS env, or `OPENXIANGDA_*` env questions**.
+- Any other skill needs to **resolve the active profile / appType / baseUrl** before write operations.
+
+## Default publish recipe (read this before any release)
+
+```bash
+# 1. preflight
+openxiangda env --profile <name>
+openxiangda auth status --profile <name>
+openxiangda update check --json   # if updateAvailable: openxiangda update install
+
+# 2. preview the change set (NEVER skip --dry-run on routine edits)
+openxiangda workspace publish --profile <name> --changed --dry-run
+
+# 3. publish only what changed
+openxiangda workspace publish --profile <name> --changed
+# or targeted:
+openxiangda workspace publish --profile <name> --page <pageCode>
+openxiangda workspace publish --profile <name> --form <formCode>
+openxiangda workspace publish --profile <name> --only pages/dashboard,forms/customer
+
+# 4. full publish only when shared/config changes intentionally affect many modules
+openxiangda workspace publish --profile <name>
+```
+
+## DO NOT
+
+- ❌ `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*` directly. They are workspace internals and miss `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE` injection.
+- ❌ Reuse a `formUuid` / `pageId` / `workflowId` / `automationId` from `dev` for `prod`. Each profile has its own resource map under `.openxiangda/state.json`.
+- ❌ Run a full `workspace publish` reflexively after editing one file.
+- ❌ Ask for AK/SK or store tokens in project files.
+
 ## Login
 
 Use ordinary platform login:

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

@@ -1,11 +1,46 @@
 ---
 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.
+description: Create / edit / publish OpenXiangda normal forms and workflow forms in `sy-lowcode-app-workspace` — schema, fields, options, validation rules, layout, linkedForm select sources, hidden permission scope keys, top-level FormEffect, workflow form bundles, single-form publish. Trigger on 创建表单 / 新建表单 / 表单字段 / 修改 schema / form field / placeholder / options / SelectField / linkedForm / FormEffect / workflow form / 审批表单页 / form schema / formCode / src/forms, or any change to `src/forms/<code>/{schema.ts,page.tsx}`.
 ---
 
 # 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.
+## When to use this skill
+
+- User wants to **create / edit a form (`src/forms/<code>/`)**, change fields, options, layout, validation, or top-level FormEffect.
+- User wants a **workflow form page** (used together with `openxiangda-workflow-automation`).
+- User wants to **publish only a form** (`workspace publish --form <code>`) or pull / inspect an existing form schema.
+- User asks how form values are persisted (option `{label, value}`, attachment shape, member fields, etc.).
+
+## Quick recipe
+
+```bash
+# 1. preflight
+openxiangda env --profile <name>
+openxiangda form list --profile <name>
+
+# 2. edit source
+#   src/forms/<formCode>/schema.ts   — fields, options, rules, top-level FormEffect[]
+#   src/forms/<formCode>/page.tsx    — presentation only
+
+# 3. preview + publish single form
+openxiangda workspace publish --profile <name> --form <formCode> --dry-run
+openxiangda workspace publish --profile <name> --form <formCode>
+```
+
+## DO / DO NOT
+
+- ✅ `defineFormSchema` from `openxiangda` and default-export it.
+- ✅ Every visible field has a concise user-facing `placeholder`. Use `tips` only for special constraints.
+- ✅ Use `SelectField` / `RadioField` for enums; for cross-form sources use `SelectField` with `optionSource.type: "linkedForm"` (and `remoteSearch: true` + `searchFieldId` when source is large).
+- ✅ Permission scope keys / sync keys / derived fields stay in schema with `behavior: "HIDDEN"`, derived from visible select/person/department fields via `valueSync`.
+- ✅ Always provide `options` for option components (Select / MultiSelect / Radio / Checkbox / CascadeSelect).
+- ❌ `AssociationFormField` for new form work (use `linkedForm` SelectField).
+- ❌ Top-level `schema.rules` as validation array. Top-level `rules` is `FormEffect[]` only (`when` / `then`).
+- ❌ Extra fields for system metadata (creator / updater / created/updated time / depts) — platform creates them automatically.
+- ❌ Developer notes / implementation comments inside labels / placeholders / tips / section titles / empty states.
+- ❌ `openxiangda form create` as page generation; it is a low-level repair command.
+- ❌ Copy `formUuid` from dev to prod — each profile has its own `formUuid` under `.openxiangda/state.json`.
 
 ## Required Workspace Flow
 

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

@@ -1,11 +1,35 @@
 ---
 name: openxiangda-inspect
-description: Read-only OpenXiangda diagnosis for app snapshots, forms, workflows, automations, and permissions using the logged-in profile token.
+description: **Read-only** OpenXiangda diagnosis — app snapshots (应用快照), forms, workflows, automations, automation executions / logs, permissions, profile drift, version mismatch, missing OSS env, broken bundle URLs, page render failures (`options is undefined`, missing styles, raw value labels). Trigger on 诊断 / 排查 / 看一下 / 对比 / diagnose / inspect / debug / why / 为什么 / 报错 / error / failure / 跳越 / drift / snapshot / 快照, or any read-only verification before / after a change. Switch to the relevant write skill (`openxiangda-form` / `-page` / `-workflow-automation` / `-permission-settings`) for remediation.
 ---
 
 # OpenXiangda Inspect
 
-Use this skill when the user asks to diagnose, compare, verify, or inspect an OpenXiangda app or resource. This skill is read-only.
+## When to use this skill
+
+- User wants to **see what's on the platform** for an app / form / page / workflow / automation / permission group.
+- User reports a **bug, error, drift, or unexpected platform state** and you need evidence before changing anything.
+- You need to **compare** local `.openxiangda/state.json` with the live platform.
+- You need **automation execution traces / logs** to understand why a trigger didn't fire or a node failed.
+
+## Decision card
+
+| Scenario | Command |
+|---|---|
+| Before any non-trivial edit to an existing app | `openxiangda app snapshot APP_XXX --profile <name> --json` |
+| Form schema looks wrong on platform | `openxiangda inspect form <code> --profile <name> --json` |
+| Workflow / automation doesn't run as expected | `openxiangda inspect workflow <code> --profile <name> --json` / `automation executions <code>` / `automation logs` / `automation diagnose <code>` |
+| Permission visibility doesn't match expectation | `openxiangda inspect permissions <formCode> --profile <name> --json` |
+| Local state out of sync with platform | `openxiangda form list / page list / workflow list / automation list --profile <name>` |
+
+## Rules
+
+- ✅ **Read-only.** This skill never writes / publishes / mutates.
+- ✅ Use **logical local codes** first; pass live IDs only when the code is missing from `.openxiangda/state.json`, and only for the current profile.
+- ✅ Cross-check unexpected values against `references/platform-data-model.md` (option `{label, value}`, attachment shape, member fields, JSONB) before claiming a bug.
+- ✅ Cross-check render / runtime issues against `references/troubleshooting.md` before patching symptoms.
+- ❌ Treat IDs from another profile as evidence — always confirm with `openxiangda env --profile <name>` first.
+- ❌ Mutate from this skill. For remediation, hand off to the relevant write skill.
 
 ## Commands
 

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

@@ -1,11 +1,45 @@
 ---
 name: openxiangda-page
-description: Build and publish OpenXiangda code pages in sy-lowcode-app-workspace using React, Ant Design, openxiangda/runtime, profile-isolated page IDs, and token-based openxiangda page commands.
+description: Build / edit / publish OpenXiangda custom code pages in `sy-lowcode-app-workspace/src/pages/<pageCode>/` using React + Ant Design + `openxiangda/runtime`. Covers app-shell portals, dashboards, workbenches, data-management lists, mobile portals, page-level connector calls, and single-page publish. Trigger on 创建页面 / 新建页面 / 修改页面 / portal / dashboard / 看板 / 驾驶舱 / 工作台 / 列表页 / mobile portal / app-shell / page.config.ts / pageCode / src/pages, JSX / React / Ant Design page work in this workspace, or any change to `src/pages/<code>/`.
 ---
 
 # OpenXiangda Page
 
-Use this when the user asks to create, update, inspect, or publish a custom code page. Normal form pages and workflow form pages also live in `sy-lowcode-app-workspace`, but under `src/forms/`; this skill covers `src/pages/`.
+## When to use this skill
+
+- User wants to **create / edit a custom code page** under `src/pages/<pageCode>/` (portal, dashboard, list/detail, workbench, mobile portal, etc.).
+- User wants to **publish only a page** (`workspace publish --page <code>`) or rebuild a single page bundle.
+- User asks about page SDK (`openxiangda/runtime`), `page.config.ts`, app-shell entry mode, namespace/style isolation, ECharts, drag-drop, antd icons, or named imports from `@ant-design/icons`.
+- User asks about **portal / admin console / mobile portal entry** — these must be app-shell code pages.
+
+## Quick recipe
+
+```bash
+# 1. preflight
+openxiangda env --profile <name>
+openxiangda page list --profile <name>
+
+# 2. edit source under src/pages/<pageCode>/
+#    page.config.ts (entry mode, route, navigation), domain/, shared/services/, shared/hooks/, components/, styles.css
+
+# 3. preview + publish single page
+openxiangda workspace publish --profile <name> --page <pageCode> --dry-run
+openxiangda workspace publish --profile <name> --page <pageCode>
+```
+
+## DO / DO NOT
+
+- ✅ Formal user-facing entries (admin console / PC portal / mobile portal) MUST be app-shell pages: `entry: { mode: "app-shell", hidePlatformNav: true, defaultRoute: "<home>" }` in `page.config.ts`.
+- ✅ Default to **native Tailwind utilities** for new pages (`bg-white`, `border-slate-200`, `grid-cols-[240px_1fr]`, ...) and `cssIsolation: "none"`. Keep namespace/shadow only for explicit legacy compatibility.
+- ✅ Split complex pages into `domain/`, `shared/services/`, `shared/hooks/`, `components/`, route/config files, `styles.css` (see `references/best-practices.md` and `references/architecture-patterns.md`).
+- ✅ List/detail/CRUD pages: follow `DataManagementList` pattern from `references/architecture-patterns.md`. Pagination + structured `filterGroup` + `OR`. Never fetch huge `pageSize` and filter in browser.
+- ✅ For external APIs use `src/resources/connectors/<code>.json` + `sdk.connector.invoke()`; for joined read-only queries use `src/resources/data-views/<code>.json`.
+- ❌ Single-file giant pages. Split per `references/best-practices.md`.
+- ❌ Hardcoded `/view/...&isRenderNav=false` URLs scattered through page code; use the runtime navigation helper.
+- ❌ shadcn token classes like `bg-card` / `text-muted-foreground` / `text-foreground` unless explicitly configured.
+- ❌ Embed a single `FormProvider` field component temporarily; navigate to a full standard form page or render a complete `StandardFormPage` instead.
+- ❌ Reuse one form UI for both PC and mobile without verifying overlay / picker / bottom-sheet behavior on both viewports.
+- ❌ Hardcode notification or platform API URLs; use `openxiangda/runtime` and `src/resources/notifications/` declarations.
 
 ## CLI Flow
 

package/openxiangda-skills/skills/openxiangda-permission-settings/SKILL.md

@@ -1,11 +1,28 @@
 ---
 name: openxiangda-permission-settings
-description: Manage OpenXiangda app roles, page permission groups, form permission groups, and lightweight form settings with profile-isolated IDs and ordinary user token permissions.
+description: Manage OpenXiangda app **roles** (角色), **page permission groups** (页面权限组 / 菜单可见), **form permission groups** (表单权限组 / 提交 / 查看 / 字段权限 / 数据范围 / 数据隔离), and **form settings** (表单设置 / 索引 / 数据管理页 / 公开访问 / public access / 分享) with profile-isolated IDs and ordinary user token permissions. Trigger on 角色 / role / 权限 / permission / 数据范围 / data scope / 字段权限 / field permission / 菜单可见 / menu visibility / 公开访问 / public access / 分享 / share, or any work touching `permission ...` / `settings ...` CLI commands or `src/resources/{roles,pagePermissionGroups,formPermissionGroups,formSettings}/`.
 ---
 
 # OpenXiangda Permission And Settings
 
-Use this skill when the user asks for app roles, visible menus/pages, form submit/view permissions, field permissions, data scopes, or app/form settings.
+## When to use this skill
+
+- User wants to **define / modify roles** for the app.
+- User wants to **gate menu / page visibility** (page permission groups).
+- User wants to **gate form submit / view / edit / data scope / field permissions** (form permission groups).
+- User wants to **publish a form publicly** or change form runtime settings, indexes, data-management page config.
+- User asks about **dynamic role governance** (role maintenance form synced to platform via automation).
+
+## DO / DO NOT
+
+- ✅ Use logical role / group codes locally; live IDs go under the active profile in `.openxiangda/state.json`.
+- ✅ For dynamic multi-role apps, build a role maintenance form + automation/JS_CODE sync, not hardcoded role logic in page code.
+- ✅ For permission scope keys, derive hidden scalars (`collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, `roleCode`) via `valueSync` from visible select/person/department fields.
+- ✅ Use page permission groups for entry visibility, form permission groups for real data isolation with condition-based data permissions.
+- ❌ Expose raw ID text fields to users for permission scopes.
+- ❌ Store platform-specific public-access IDs locally; CLI resolves by `appType + formUuid` per profile.
+- ❌ Reuse role / permission-group IDs across profiles.
+- ❌ Use AK/SK or legacy `/dingtalk-api/v1.0` — the logged-in user must have the matching app permission.
 
 ## Required Context
 

package/openxiangda-skills/skills/openxiangda-workflow-automation/SKILL.md

@@ -1,11 +1,35 @@
 ---
 name: openxiangda-workflow-automation
-description: Build, validate, publish, enable, and inspect OpenXiangda workflow definitions and automations with profile-isolated resource IDs and ordinary user token permissions.
+description: Build / validate / publish / enable / inspect OpenXiangda **workflows** (审批流程 / approval / approve / reject / transfer / withdraw, v3 graph, JS_CODE trusted_node) and **automations** (自动化 / 集成 / 定时任务 / cron / form data submit/update/delete events, form field change, workflow task / process events, message notifications). Includes architecture boundary between workflow and normal status-machine forms, code-first workflows (`src/workflows/<code>/workflow.ts`) and code-first automations (`src/automations/<code>/index.ts`). Trigger on 审批 / 流程 / workflow / approval / process / 节点 / 并行分支 / 条件分支 / 代办 / 转交 / 撤回 / 驳回 / 自动化 / automation / cron / 定时 / 提交后 / 字段变更 / JS_CODE / trusted_node / src/js-code-nodes.
 ---
 
 # OpenXiangda Workflow And Automation
 
-Use this skill when the user asks for approval workflows, workflow forms, automation rules, scheduled jobs, form-event triggers, or process-triggered automation in OpenXiangda.
+## When to use this skill
+
+- User asks for **approval workflows / 审批 / 流程 / approve / reject / transfer / withdraw / process records / approval-node side effects**.
+- User asks for **automation / 自动化 / cron / 定时 / form-data-submitted/updated/deleted / field-changed / workflow-task-approved / message notification triggers**.
+- User asks for **JS_CODE backend script** (cross-form query, batch update, terminate process, external HTTP, complex orchestration that frontend can't handle).
+- User wants **code-first workflow / automation** (TypeScript source under `src/workflows/` or `src/automations/`).
+
+## Boundary — workflow vs. status field
+
+**Most business lifecycle flows are NOT workflows.** For ordinary `pending → processing → resolved → closed`, use a normal form + `status` field + responsibility fields + action-log form + state machine + automation/JS_CODE.
+
+Create a workflow only when the scenario has **real approval semantics**: approvers, approval tasks, agree/reject actions, opinions, node-level field permissions, process records, approval-node side effects.
+
+## DO / DO NOT
+
+- ✅ New AI-authored automations: prefer **code-first** `automation_code_ts` (`src/automations/<code>/index.ts` + `definition.code.json` + `preview.json`).
+- ✅ New AI-authored workflows that don't need canvas editing: prefer **code-first** `src/workflows/<code>/workflow.ts` using `openxiangda/workflow`.
+- ✅ JS_CODE V2 trusted_node: source in TypeScript under `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`. Run `pnpm build-js-code --script <code>` (validates with `tsc` first).
+- ✅ Use `trigger_v2` for new automation triggers; CLI fills root `appType` / `formUuid` from active profile when `--form-code` is provided.
+- ✅ Use logical `workflowCode` / `automationCode` locally; live IDs are profile-isolated under `.openxiangda/state.json`.
+- ✅ `ctx.logger.debug/info/warn/error(message, data?)` at every important step — inspect via `automation executions` / `automation logs` / `automation diagnose`.
+- ❌ JS_CODE for simple UI interactions, ordinary form validation, or display-only logic — those belong to a normal React code page.
+- ❌ Workflow definitions for non-approval status changes — use a status field instead.
+- ❌ Copy `workflowId` / `automationId` across profiles. Always create/bind separately for each profile.
+- ❌ Inline large JS code blobs in v3 JSON for new work — use trusted_node TypeScript snapshots.
 
 ## Architecture Boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.36",
+  "version": "1.0.38",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {