openxiangda 1.0.35 → 1.0.37

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/references/style-system.md

@@ -9,8 +9,9 @@
 1. **业务页面默认写原生 Tailwind**：优先使用 `bg-white`、`border`、`border-slate-200`、`text-slate-600`、`shadow-sm`、`rounded-lg`、`p-4`、`gap-4`、`grid-cols-[240px_1fr]` 这类 Tailwind 原生类和任意值。
 2. **不要强制平台 token**：不要把 `bg-container`、`text-secondary`、`rounded-form`、`shadow-card` 当默认示例或默认范式。历史项目或平台组件需要时可以兼容使用，但新业务页面不推荐主动依赖。
 3. **不要直接套 shadcn token**：`bg-card`、`text-muted-foreground`、`text-foreground`、`bg-background` 等不是 Tailwind 原生类。除非项目已经在 `tailwind.config.cjs` 明确配置这些 token，否则必须改成 Tailwind 原生类或任意值。
-4. **保留 OpenXiangda 隔离能力**：Tailwind 仍通过 `.sy-app-workspace` namespace 输出，workspace 仍扫描 `openxiangda` 包内容，平台组件 safelist 仍保留。
-5. **CSS 作用域要收敛**：页面级 CSS 写在 `styles.css`，选择器限定在 `.sy-app-workspace` 或页面根类下，避免污染宿主平台。
+4. **默认不启用样式隔离**：新发布页面默认 `cssIsolation: "none"`，Tailwind 类按原样输出，不需要 `.sy-app-workspace` 前缀即可生效。
+5. **legacy 隔离仅用于兼容**：历史页面或显式配置 `cssIsolation: "namespace" | "shadow"` 时，runtime 仍会保留 `.sy-app-workspace`、legacy portal 和旧样式前缀。
+6. **CSS 作用域要收敛**：页面级 CSS 写在 `styles.css`，选择器优先限定在页面根类下，避免无意覆盖宿主平台或其他页面。
 
 ---
 
@@ -60,12 +61,12 @@ export function DashboardPage() {
 ### 2.4 局部 CSS
 
 ```css
-.sy-app-workspace .queue-booking-page {
+.queue-booking-page {
   min-height: 100%;
   background: #f8fafc;
 }
 
-.sy-app-workspace .queue-booking-page__calendar-grid {
+.queue-booking-page .queue-booking-page__calendar-grid {
   display: grid;
   grid-template-columns: repeat(7, minmax(120px, 1fr));
   gap: 12px;
@@ -113,11 +114,11 @@ module.exports = {
 
 这个配置的作用：
 
-- `openxiangdaPreset` 保留 `.sy-app-workspace` namespace、平台组件 safelist 和平台组件需要的工具类。
+- `openxiangdaPreset` 保留平台组件 safelist、平台 token 兼容类和平台组件需要的工具类；不再强制 Tailwind 输出 `.sy-app-workspace` 前缀。
 - `...openxiangdaContent` 确保平台组件内部 class 会被 Tailwind 扫描到。
 - `blocklist` 避免 Tailwind 误生成日期字符串相关的异常类。
 
-不要为了“更自由”移除这些平台构建能力；自由写 Tailwind 原生类和保留构建隔离能力并不冲突。
+不要移除这些平台构建能力；自由写 Tailwind 原生类和保留平台组件兼容能力并不冲突。
 
 ---
 
@@ -160,21 +161,15 @@ body {
 
 ## 5. Ant Design 和弹层
 
-PC 控件优先用 `antd`，移动端控件优先用 `antd-mobile`。弹层必须挂到当前页面容器或 `.sy-app-workspace` 内，避免宿主平台污染或滚动容器裁切：
+PC 控件优先用 `antd`，移动端控件优先用 `antd-mobile`。默认 `cssIsolation: "none"` 时使用 Ant Design 默认 `ant` class 和 `document.body` 弹层容器即可；只有 legacy `namespace/shadow` 页面才需要显式挂到当前隔离容器：
 
 ```tsx
-<ConfigProvider
-  getPopupContainer={(trigger) =>
-    trigger?.closest('.sy-app-workspace') ??
-    (document.querySelector('.sy-app-workspace') as HTMLElement) ??
-    document.body
-  }
->
+<ConfigProvider>
   <App />
 </ConfigProvider>
 ```
 
-局部组件也可以使用 `getPopupContainer={(trigger) => trigger.parentElement ?? document.body}`。不要无作用域覆盖 `.ant-select-selector`、`.ant-modal` 等私有 class；确实需要覆盖时限定在页面根类下。
+legacy 页面可使用 `getPopupContainer={(trigger) => trigger?.closest(".sy-app-workspace") ?? document.body}`。不要无作用域覆盖 `.ant-select-selector`、`.ant-modal` 等私有 class；确实需要覆盖时限定在页面根类下。
 
 ---
 
@@ -188,9 +183,10 @@ OpenXiangda 仍保留部分平台语义类和 CSS 变量，主要用于：
 
 常见兼容类包括 `text-primary`、`text-secondary`、`bg-container`、`bg-layout`、`border-secondary`、`rounded-form`、`shadow-card` 等。AI 编写新业务页面时不要默认使用这些类；除非用户明确要求跟随平台变量主题，或当前项目已有一致的 token 体系。
 
-如果需要统一主题，推荐把主题限制在 `.sy-app-workspace` 或应用根类下：
+如果需要统一主题，推荐把主题限制在应用根类下；兼容旧页面时也可以同时声明 `.sy-app-workspace`：
 
 ```css
+.theme-brand,
 .sy-app-workspace.theme-brand {
   --sy-color-primary: #0f766e;
   --sy-radius-md: 8px;
@@ -218,5 +214,5 @@ warning 不会阻断构建，但它通常意味着页面会出现“颜色、边
 - [ ] 页面样式默认使用 Tailwind 原生类和任意值，而不是平台 token 类？
 - [ ] 没有使用未配置的 shadcn token 类，例如 `bg-card`、`text-muted-foreground`、`text-foreground`？
 - [ ] `tailwind.config.cjs` 保留 OpenXiangda preset、content 扫描和 blocklist？
-- [ ] 业务 CSS 限定在 `.sy-app-workspace` 或页面根类下？
-- [ ] antd / antd-mobile 弹层设置了合适的挂载容器？
+- [ ] 业务 CSS 限定在页面根类下，而不是全局裸覆盖？
+- [ ] 只有 legacy `namespace/shadow` 页面才额外配置 `.sy-app-workspace` 弹层容器？

package/openxiangda-skills/references/troubleshooting.md

@@ -23,18 +23,18 @@
 
 **症状**：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';
+**根因**：新页面默认 `cssIsolation: "none"`，弹层使用 `document.body` 和默认 Ant Design 样式即可。只有历史页面显式启用 `cssIsolation: "namespace" | "shadow"` 时，弹层渲染到 `document.body` 才可能脱离 legacy 样式作用域；移动端 Popup 也可能因 namespace 未被继承而失去样式。
+
+**解决方案**：
+1. 新页面优先保持 `cssIsolation: "none"`，不要为了修弹层问题手动加 `.sy-app-workspace`。
+2. legacy `shadow` 页面优先迁移为 `none`；无法迁移时可使用 `namespace` 兼容模式。
+3. legacy 页面为 antd `ConfigProvider` 配置 `getPopupContainer` 指向页面根容器。
+4. 对于 legacy antd-mobile 页面，确保 `Popup` / `Modal` 的 `getContainer` 指向正确容器，并按需补 namespace class。
+
+**legacy 示例**：
+```tsx
+import { useRef } from 'react';
+import { ConfigProvider } from 'antd';
 
 const rootRef = useRef<HTMLDivElement>(null);
 
@@ -188,7 +188,7 @@ export default defineConfig({
 **解决方案**：
 1. 在 `vite.config.ts` 的 `optimizeDeps.include` 中显式添加 `antd-mobile`，避免运行时多次预构建。
 2. 调整 Tailwind preflight 策略，确保不会覆盖 antd-mobile 的基础样式（必要时关闭 preflight 或使用 `important` 选择器）。
-3. 确保 antd-mobile 组件渲染在 `sy-app-workspace` namespace 容器内，弹层 `getContainer` 指向该容器。
+3. 仅 legacy `namespace/shadow` 页面需要确保 antd-mobile 组件渲染在 `sy-app-workspace` namespace 容器内，弹层 `getContainer` 指向该容器；新页面默认不需要。
 
 **示例**：
 ```typescript

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