openxiangda 1.0.264 → 2.0.0-alpha.2

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

@@ -1,154 +0,0 @@
----
-name: openxiangda-page
-description: "Build, edit, and publish OpenXiangda custom code pages in sy-lowcode-app-workspace/src/pages using React, Ant Design, and openxiangda/runtime. Covers portals, dashboards, workbenches, data-management lists, mobile pages, connector calls, filters, search forms, and single-page publish. Trigger on 创建页面, 修改页面, portal, dashboard, 看板, 工作台, 列表页, mobile portal, page.config.ts, pageCode, JSX, React, or src/pages changes."
----
-
-# OpenXiangda Page
-
-## 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 lists use row data views + `sdk.dataView.query`; for stable dashboard metrics use aggregate data views + `sdk.dataView.stats`.
-- ✅ Choose data view `storageMode` deliberately: `materialized` for refreshed reports/lists that tolerate delay, `live` for bounded real-time multi-form reads.
-- ✅ For reusable backend orchestration use App Function (`src/functions/<functionCode>/index.ts` + `src/resources/functions/<functionCode>.json`) and call `sdk.function.invoke(code, { input })`; keep page components out of multi-table business orchestration.
-- ✅ 家长、学生、教师、班主任身份或班级/监护关系页面使用 `sdk.organization.schoolContact.*`；先读 `references/school-contact-relations.md`。用 `SCHOOL_HEAD_TEACHER` 判断全局身份，用 `teachers.list({ classId, isHeadTeacher: true })` 判断具体班主任班级；默认使用已登录用户的租户内全部关系，仅在业务要求时声明 self/class 收紧范围，并保持服务端分页。
-- ✅ Filters, search bars, modal forms, drawers, and inline edits use platform components for platform data fields, otherwise `antd` / `antd-mobile` controls.
-- ❌ 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.
-- ❌ Raw native form controls in AI-authored page code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers/uploaders). Use platform components or `antd` / `antd-mobile`.
-- ❌ 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
-
-```bash
-openxiangda env --profile <name>
-openxiangda page list --profile <name>
-cd /path/to/sy-lowcode-app-workspace
-openxiangda workspace publish --profile <name>
-```
-
-For a page-only edit, prefer targeted publish:
-
-```bash
-openxiangda workspace publish --profile <name> --page <pageCode>
-```
-
-If multiple files changed and the target is not obvious, preview first:
-
-```bash
-openxiangda workspace publish --profile <name> --changed --dry-run
-openxiangda workspace publish --profile <name> --changed
-```
-
-If the workspace does not exist yet, initialize it first:
-
-```bash
-openxiangda workspace init ./my-app-workspace --profile <name> --app-name "应用名称"
-cd ./my-app-workspace
-pnpm install
-```
-
-Use `--app-type APP_XXX` only when the user explicitly provides an existing app to reuse.
-
-Direct publish is only for already built assets or targeted repair:
-
-```bash
-openxiangda page publish dashboard \
-  --entry-url https://cdn.example.com/dashboard/index.js \
-  --css-urls https://cdn.example.com/dashboard/style.css \
-  --version 1.0.0 \
-  --build-id 20260521120000 \
-  --change <change> \
-  --profile <name>
-
-# The command above stages only. Review the immutable release:
-openxiangda page releases --profile <name> --json
-
-# In a normal app release, include its PageRelease entry in staged-resources.json
-# and atomically activate it with the other staged children:
-openxiangda release app-finalize --change <change> \
-  --staged-resources-json staged-resources.json --profile <name>
-
-# Page-only repair may still activate explicitly:
-openxiangda page activate <releaseId> --change <change> --profile <name>
-
-# Historical activation is explicit and audited:
-openxiangda page rollback <releaseId> --rollback \
-  --change <change> --reason "restore reviewed page release" --profile <name>
-```
-
-Direct Page publish always freezes `pages/snapshot` first and sends the active parent plus all page revisions and active-asset hashes; a new page uses expected revision `0`. A single-page patch clone-forwards unchanged pages from the active immutable Page Release, so the staged result remains a complete activatable app-level Page Release. It never refreshes or retries a stale parent. Keep it staged for normal multi-resource work and pass its `PageRelease` entry to root atomic `app-finalize`; use direct Page activation only for an intentional page-only repair.
-
-## Development Rules
-
-Read these references only when editing page code:
-
-- `references/pages/workspace-structure.md`
-- `references/pages/app-shell.md` — formal backend / PC portal / mobile portal entry pattern. Read before creating any user-facing main entry or admin console.
-- `references/best-practices.md` — initialized examples for modular pages, status lifecycles, role governance, high-performance queries, portal shells, and interactive workbenches. Read before scaffolding complex pages or data management pages.
-- `references/pages/page-sdk.md`
-- `references/school-contact-relations.md` — 家校关系权限、分页查询、返回字段以及 Page SDK/App Function 示例。创建家长、学生或班级关系页面前读取。
-- `references/notifications.md` — notification resources and `sdk.notification` usage. Read before adding reminders, alerts, or message templates to a page.
-- `references/pages/publish-flow.md`
-- `references/style-system.md` — style isolation defaults, Tailwind/CSS guidance, and legacy namespace compatibility. Read before writing substantial page CSS or Tailwind classes.
-- `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, and recommended `src/pages/<pageCode>/` layout. Read before scaffolding a new page or list view.
-- `references/component-guide.md` — platform component first, `antd` / `antd-mobile` fallback, and native-control ban for AI-authored app code. Read before introducing a new component.
-- `references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and their fixes. Read when something does not behave as expected.
-
-## Rules
-
-- Keep `pageCode` stable and use it as the local logical key.
-- Formal user-facing entries such as admin consoles, PC portals, and mobile portals must be app-shell code pages. Declare `entry: { mode: "app-shell", hidePlatformNav: true, defaultRoute: "<home-route>" }` in `page.config.ts`.
-- Do not generate single-file large pages. Split complex code pages into `domain/`, `shared/services/`, `shared/hooks/`, shared/page-local `components/`, route/config files, and `styles.css` as described in `references/best-practices.md`.
-- Keep view code thin. Page components call hooks/services; business rules, state transition rules, permission predicates, and query builders live outside TSX and are reusable by PC and mobile pages.
-- All visible page copy must be end-user-facing business text. Do not put developer explanations, implementation notes, schema descriptions, or "this module is generated by..." text into sections, cards, alerts, empty states, tooltips, or helper copy.
-- Store live `pageId`, `routeKey`, and `legacyFormUuid` under the current profile only.
-- Use `openxiangda/runtime` for platform data access instead of hardcoding backend URLs in page code.
-- 家校关系必须通过 `sdk.organization.schoolContact` / `ctx.organization.schoolContact` 读取；班主任班级使用 `teachers.list` 的 `isHeadTeacher`，不要用全局角色推断具体班级，也不要直连钉钉、查询系统表或用同班成员推断亲属关系。
-- For reminders, alerts, and business messages, declare `src/resources/notifications/` first and call `sdk.notification`; do not hardcode notification API URLs.
-- For backend business logic shared by pages, automations, or workflows, declare an App Function and call `sdk.function.invoke`; do not duplicate the same multi-form query/connector/notification orchestration in page code.
-- Before hand-writing mature UI behavior, consult `references/component-guide.md` and use established libraries: platform components for platform data fields, antd/antd-mobile for controls and overlays, ECharts for charts, GSAP for complex animation timelines, and maintained packages such as dnd-kit for drag/drop. Do not rebuild mature controls with raw DOM/native inputs.
-- Named imports from `@ant-design/icons` are supported by the `openxiangda` workspace build proxy, which enumerates icon module exports at runtime.
-- Publish through `openxiangda workspace publish --profile <name>` unless there is a specific repair reason to call `page publish` directly.
-- After editing one code page, publish with `--page <pageCode>` instead of triggering all forms/pages. Use `--changed --dry-run` before `--changed` when git touched several modules.
-- Do not create custom code pages by writing platform schema directly. The source is React workspace code plus `page.config.ts`.
-- Do not scatter hardcoded `/view/...&isRenderNav=false` URLs through page code. Use the runtime navigation API or the local route helper generated for the app shell.
-- Platform menus should bind only the formal app-shell code page for user-facing entry points. Original forms, workflows, and native view pages may remain as development / maintenance resources or permission targets, but should not become the product navigation shell.
-- For prod, explicitly run with `--profile prod`; never rely on the current profile for release operations.
-- Follow the style system in `references/style-system.md`: default to native Tailwind utilities and arbitrary values for business pages (`bg-white`, `border`, `border-slate-200`, `text-slate-600`, `grid-cols-[240px_1fr]`, etc.). New pages default to `cssIsolation: "none"` and do not need `.sy-app-workspace`; keep namespace/shadow handling only for legacy pages that explicitly configure it. Do not treat platform token classes as the default authoring pattern, and do not use shadcn token classes such as `bg-card`, `text-muted-foreground`, or `text-foreground` unless the workspace explicitly configures them.
-- For list / detail / CRUD pages, follow `references/architecture-patterns.md` (e.g. `DataManagementList`) before writing custom data-fetching loops.
-- Query pages must use pagination with structured conditions. Do not fetch a large `pageSize` and filter in the browser; avoid default `searchKeyWord`, and build multi-field fuzzy search with explicit `filterGroup` + `OR`.
-- Pick components per `references/component-guide.md`: prefer the platform component, fall back to Ant Design / antd-mobile wrappers, and only build a custom component when neither fits. In app/workspace page code, do not emit raw `<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, or hand-written uploaders.
-- When a page misbehaves (lost styles, `options is undefined`, option labels showing raw values, etc.), consult `references/troubleshooting.md` before patching symptoms.
-- For custom portal pages and business modals, do not temporarily embed a single `FormProvider` field component from the standard form runtime. If a standard component is required, navigate to a full standard form page or render a complete `StandardFormPage` inside a dedicated carrier route.
-- If a complete custom edit surface intentionally embeds platform fields in `FormProvider`, set `config.api` from `usePageFormRuntimeApi()` (or `createPageFormRuntimeApi(sdk)` outside hooks). Never hand-write a JSON-only `sdk.request` bridge; it breaks Blob preview and download contracts.
-- Keep PC and mobile portal styles separate. Do not share one form UI implementation across both viewports unless the surrounding shell, modal layer, date picker, and bottom-sheet behavior have been tested in both contexts.
-- After introducing Ant Design overlays, date/datetime fields, or mobile bottom-sheet selectors, verify that global button, modal, picker, and sheet styles do not leak into the host business page.

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

@@ -1,209 +0,0 @@
----
-name: openxiangda-permission-settings
-description: Manage OpenXiangda app **roles** (角色), **page permission groups** (页面权限组 / 菜单可见), **form permission groups** (表单权限组 / 提交 / 查看 / 字段权限 / 数据范围 / 数据隔离), account/role governance patterns, query-parameter authorization boundaries, and **form settings** (表单设置 / 索引 / 数据管理页 / 公开访问 / public access / 分享) with profile-isolated IDs and ordinary user token permissions. Trigger on 角色 / role / 权限 / permission / RBAC / 账号权限 / account permission / 组织账号 / organization account / 平台账号 / 数据范围 / 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
-
-## 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).
-- User asks about **platform accounts, organization accounts, account-role assignment, RBAC, or query-parameter access**.
-
-## DO / DO NOT
-
-- ✅ Before account/role/permission design, run `openxiangda design gates --topic permissions --json` and choose one mode: `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`.
-- ✅ Write a permission matrix before implementation: account source, role member source, page groups, form groups, data scope, field access policy, backend checks, query parameter boundary, and publish order.
-- ✅ 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.
-- ✅ For app-managed platform accounts/departments, use `sdk.organization.*` / `ctx.organization.*`. Read-only list/detail operations require `app:organization:read` or `app:organization:manage`; writes and password operations require `app:organization:manage`.
-- ✅ For delegated administrators such as 校区管理员, put role-setting API permissions in the role manifest with `apiPermissionCodes`; use `app:role:manage` for app role creation/member assignment/API-permission assignment, and add page/form/organization management permission codes only when needed.
-- ✅ If a delegated administrator creates another role that can also manage accounts, roles, or permission groups, publish that new role with its own `apiPermissionCodes`.
-- ❌ Expose raw ID text fields to users for permission scopes.
-- ❌ Treat query parameters as sensitive authorization. They may carry context, filters, or ticket input only.
-- ❌ Treat `PermissionBoundary`, button hiding, route hiding, or frontend role checks as the authority for sensitive data.
-- ❌ Hardcode role strings in pages without backing roles/page groups/form groups or App Function checks.
-- ❌ Give a user a business admin role but forget to bind `app:role:manage`, then expect role creation or role-member assignment to work.
-- ❌ Bypass OpenXiangda SDK and call platform account/organization write APIs directly.
-- ❌ 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
-
-Before changing permissions:
-
-```bash
-openxiangda env --profile dev
-openxiangda auth status --profile dev
-openxiangda workspace bind --profile dev --app-type APP_XXX
-```
-
-The logged-in user must have the matching app permission. Do not use AK/SK or legacy `/dingtalk-api/v1.0`.
-
-For design work, also run:
-
-```bash
-openxiangda design gates --topic permissions --json
-```
-
-Resolve the permission mode before writing resources:
-
-- `managed-platform-account`: the app creates/maintains platform accounts,
-  departments, and role members.
-- `existing-platform-user-assignment`: the app selects existing platform users
-  and assigns app roles/business scopes.
-- `static-role-permission`: fixed app roles and permission groups, no in-app
-  account governance.
-- `query-param-context`: query parameters are only context, filters, or ticket
-  input; sensitive authorization still comes from roles, grants, form groups,
-  or App Function checks.
-
-## Roles
-
-Create app roles first:
-
-```bash
-openxiangda permission role-list --profile dev
-openxiangda permission role-create sales --name "销售" --profile dev
-```
-
-Use role codes in permission group JSON. Bind existing role IDs only inside the current profile:
-
-```bash
-openxiangda permission role-bind sales --role-id <id> --profile dev
-```
-
-`role-users` and `role-add-users` accept either a role UUID or a logical role
-code. When a code has no profile-local binding, the CLI resolves it from the
-current application's role list and requires exactly one matching code; missing
-or ambiguous matches fail explicitly instead of sending the code as a role ID.
-
-For dynamic multi-role apps, do not hardcode role behavior only in page code. Create a role maintenance form and sync it to platform roles with automation / JS_CODE. Visible scope fields should be maintainable controls: personnel/department fields for people and orgs, `SelectField` / `RadioField` for enums, and `SelectField` with `optionSource.type: "linkedForm"` for records maintained by other forms. When the source form can have many records, set `remoteSearch: true` and `searchFieldId` so typing in the dropdown triggers an SDK query instead of loading every record. If form permission groups need scalar matching, derive hidden keys such as `collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, and `roleCode`; do not expose raw ID text fields to users. Use page permission groups for entry visibility and form permission groups with condition-based data permissions for real data isolation.
-
-For managed platform account governance, use organization/account forms and sync
-functions as a closed loop: organization units, system accounts, role
-assignments, roles resources, page groups, form groups, sync App Functions, and
-backend role/scope checks. Platform account access must go through
-`sdk.organization` or `ctx.organization`; give read-only operators
-`app:organization:read` and require `app:organization:manage` for writes and
-password operations.
-
-## Page Permission Groups
-
-Page permission groups control menu/page visibility:
-
-```bash
-openxiangda permission page-group-create sales_pages --name "销售页面" --roles sales --form-codes customer,orders --profile dev
-openxiangda permission page-group-create portal_pages --name "门户页面" --page-codes portal_pc,portal_mobile --profile dev
-```
-
-Use `--page-codes` or `--menu-codes` for custom code page menus; the CLI resolves the permission group to the published menu ID and keeps required page ID, route key, and legacy `PAGE_...` runtime aliases in the same group so the platform editor can still round-trip the selection. Use `--form-codes` for form menus; the CLI resolves forms to profile-local form UUIDs. Empty target lists mean all menus/pages are visible to matched roles. Only pass `--no-runtime-aliases` after confirming the target platform checks menu IDs directly at runtime.
-
-For Phase 6 React SPA apps, define menu visibility and direct route access with
-resource codes instead of old platform menu-tree-only targets:
-
-```json
-{
-  "code": "sales_spa_pages",
-  "name": "销售 SPA 页面",
-  "roles": ["sales"],
-  "menuCodes": ["sales_dashboard", "customer_data"],
-  "routeCodes": ["sales.dashboard", "customer.data"],
-  "pathPatterns": ["/view/:appType/admin/sales/*"]
-}
-```
-
-Or create from CLI:
-
-```bash
-openxiangda permission page-group-create sales_spa_pages \
-  --name "销售 SPA 页面" \
-  --roles sales \
-  --menu-codes sales_dashboard,customer_data \
-  --route-codes sales.dashboard,customer.data \
-  --path-patterns '/view/:appType/admin/sales/*' \
-  --profile dev
-```
-
-Do not hardcode role checks in React pages. Use backend runtime bootstrap,
-`useAppMenus()`, `useCanAccessRoute()`, and `PermissionBoundary` from
-`openxiangda/runtime/react` for display control. Backend form, field, data,
-workflow, file, and connector permissions remain authoritative.
-
-## Form Permission Groups
-
-Form permission groups control submit/view permissions, data scope, operations, and fields:
-
-```bash
-openxiangda permission form-group-create sales_view --form-code customer --name "销售查看" --type view --roles sales --operations view --profile dev
-```
-
-For advanced field permissions and data permission conditions, pass JSON files:
-
-```bash
-openxiangda permission form-group-create sales_limited \
-  --form-code customer \
-  --name "销售只看自己" \
-  --type view \
-  --roles sales \
-  --data-scope-json data-scope.json \
-  --field-permissions-json fields.json \
-  --field-access-policy-json field-access-policy.json \
-  --data-permission-json data-permission.json \
-  --profile dev
-```
-
-`fieldPermissions` is the frontend display-default state. Use `fieldAccessPolicy`
-for real backend read/write field access (`edit`, `readonly`, `hidden`) with
-`defaultAccess` plus field-ID exceptions.
-
-For governed application publishing, declare groups under
-`src/resources/formPermissionGroups` and publish them through exact
-`resource publish ... --only ... --change ...` scope. The CLI folds changed
-groups into the owning Form's immutable FormRelease, freezes a permission-group
-parent hash, and keeps live rows unchanged until Root App finalize. The
-low-level `permission form-group-create/update/delete` commands are for
-intentional maintenance and diagnostics, not an atomic multi-resource release.
-
-## Inspection
-
-```bash
-openxiangda permission form-summary --form-code customer --profile dev --json
-openxiangda permission menu-permissions --profile dev --json
-openxiangda permission snapshot --profile dev --form-codes customer,orders --json
-```
-
-When auditing many roles or permission groups, prefer `openxiangda permission
-snapshot` over looping `role-list`, `page-group-list`, or `form-group-list`.
-The snapshot command uses the platform batch endpoint and returns roles, page
-permission groups, and form permission groups in one request.
-
-## Form Settings
-
-Use settings commands for form runtime settings, field indexes, data management pages, and public access:
-
-```bash
-openxiangda settings get customer --profile dev --json
-openxiangda settings save customer --settings-json settings.json --profile dev
-openxiangda settings indexes customer --profile dev --json
-openxiangda settings indexes-save customer --indexes-json indexes.json --profile dev
-openxiangda settings data-management-save customer --config-json data-management.json --profile dev
-openxiangda settings public-access-save customer --public true --description "公开填报" --profile dev
-```
-
-Do not store platform-specific public access IDs locally. The CLI resolves by `appType + formUuid` for the current profile.
-
-## References
-
-- Permission model and examples: `references/permissions-settings.md`
-- Account/role design modes: `references/permission-design-patterns.md`
-- Dynamic role governance and data-isolation pattern: `references/best-practices.md`
-- Profile-isolated IDs: `references/workspace-state.md`
-- API fields: `references/openxiangda-api.md`

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

@@ -1,201 +0,0 @@
----
-name: openxiangda-workflow-automation
-description: "Build, validate, publish, enable, and inspect OpenXiangda workflows and automations: approval flows, v3 graphs, JS_CODE trusted_node, App Function function_call, cron, form events, field changes, workflow events, and notifications. Includes the workflow versus status-machine boundary, code-first workflows, code-first automations, JS_CODE node scripts, and reusable App Functions. Trigger on 审批, 流程, workflow, automation, cron, JS_CODE, trusted_node, App Function, src/js-code-nodes, or src/functions."
----
-
-# OpenXiangda Workflow And Automation
-
-## 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 asks for **App Function / function_call** reusable backend logic that pages, automations, and workflows should share.
-- 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: prefer **semantic DSL** `src/workflows/<code>/workflow.ts` using `defineWorkflow`; compile it to v3 designer JSON with `openxiangda workflow compile`.
-- ✅ Runtime workflow pages: use `sdk.process.resolveCapabilities(...)` or `ProcessActionBar` / `ProcessTimeline` from `openxiangda/runtime/react`; do not hard-code buttons.
-- ✅ Runtime task centers: use `sdk.workCenter.listItems({ boxType: "todo" | "done" | "cc" | "initiated" })` and `sdk.workCenter.getStats()` for current-user lists/counts; do not read workflow logs, automation logs, or raw process-task tables for end-user todo pages.
-- ✅ Before custom workflow UI or delayed approval work, read `references/workflow-v3.md` sections **Cookbook: draft, start, return, resubmit** and **Capability action reference** for payloads, required IDs, and refresh rules.
-- ✅ Delayed approval start: save the process-form record first with `StandardFormPage submitBehavior="save-draft"` or `sdk.form.create({ formUuid, data, saveAsDraft: true, startProcess: false })`, then start approval in place with `sdk.process.startFromExistingInstance({ formUuid, formInstId })` or `StandardFormPage submitBehavior="start-existing-process"`.
-- ✅ Return-to-initiator flows: use `returnPolicy: { scopeType: "initiator", resubmitMode: "resume_current" | "replay" }` or `flow.action.returnToInitiator()`. The runtime capabilities protocol exposes `resubmit` only for pending `originator_return` tasks; return to a previous approval node continues through the normal `approve` action.
-- ✅ Reusable backend business logic: prefer **App Function** (`src/functions/<functionCode>/index.ts` + `src/resources/functions/<functionCode>.json`), then call it from page `sdk.function.invoke` or automation/workflow `function_call`.
-- ✅ JS_CODE V2 trusted_node: source in TypeScript under `src/js-code-nodes/<scriptCode>/index.ts`, `src/automations/<resourceCode>/index.ts`, or `src/functions/<functionCode>/index.ts`. Run `pnpm build-js-code --script <code>`; an explicit selector validates/builds only that entry plus its transitive/shared/ambient dependencies, while an unscoped command validates the whole workspace.
-- ✅ 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, display-only logic, or backend logic that should be reused outside one graph node.
-- ❌ 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
-
-Most business lifecycle flows are not workflows. For ordinary status changes such as `pending -> processing -> resolved -> closed`, use a normal form, a `status` field, redundant responsibility fields, an action-log form, a domain state machine, a service method, and optional automation / JS_CODE.
-
-Create workflow definitions only when the scenario has real approval semantics: approvers, approval tasks, agree/reject actions, approval opinions, node-level permissions, process records, or approval-node side effects.
-
-## Required Context
-
-Before any write:
-
-```bash
-openxiangda env --profile dev
-openxiangda auth status --profile dev
-openxiangda workspace bind --profile dev --app-type APP_XXX
-```
-
-Resolve logical form codes through `.openxiangda/state.json`:
-
-```bash
-openxiangda form list --profile dev
-openxiangda form bind customer --form-uuid FORM_XXX --profile dev
-```
-
-## Workflow Flow
-
-1. Create or update `src/workflows/<workflowCode>/workflow.ts` with `defineWorkflow`.
-2. Compile and check it:
-   ```bash
-   openxiangda workflow compile src/workflows/customer_approval/workflow.ts --check
-   openxiangda workflow compile src/workflows/customer_approval/workflow.ts \
-     --out-definition src/resources/workflows/customer_approval/definition.v3.json \
-     --out-preview src/resources/workflows/customer_approval/preview.json
-   ```
-3. Prefer resource manifests:
-   ```json
-   {
-     "code": "customer_approval",
-     "formCode": "customer",
-     "workflowFile": "../../../workflows/customer_approval/workflow.ts",
-     "definitionFile": "definition.v3.json",
-     "previewFile": "preview.json",
-     "publish": true
-   }
-   ```
-   Then run `openxiangda resource validate --profile dev`, `openxiangda resource publish --profile dev --dry-run`, and finally `openxiangda resource publish --profile dev`.
-4. For low-level repair, validate compiled or pulled JSON:
-   ```bash
-   openxiangda workflow validate --definition-json workflow.json --publish --profile dev
-   ```
-5. Low-level create and bind:
-   ```bash
-   openxiangda workflow create customer_approval --form-code customer --definition-json workflow.json --profile dev
-   ```
-6. Publish:
-   ```bash
-   openxiangda workflow publish customer_approval --profile dev
-   openxiangda workflow list --profile dev --json
-   ```
-
-Use `workflow pull` to inspect the live definition. Use `workflow list --json` after publishing and confirm the target shows `isPublished: true`; resource publish can create/update a draft without activating it. `workflow list` hides platform shell workflows with empty `resourceCode` by default; use `--all` only for raw platform diagnostics. Use logical workflow codes locally; never copy a workflow ID from one profile to another.
-
-## JS_CODE V2
-
-JS_CODE is the backend execution escape hatch for workflow and automation. Use it when the logic must run on the server after a backend trigger, such as a fixed cron schedule, a form date-field schedule, a form submit/update/delete/field-change event, or a workflow approval/process event. It is appropriate for cross-form data queries, create/update/batch update operations, process termination, platform API calls, external HTTP calls, and complex orchestration that the frontend cannot handle reliably.
-
-App Function is the reusable backend execution model. Use it when the logic should be called by custom pages, multiple automations, workflows, or the runtime API. Source lives in `src/functions/<functionCode>/index.ts`; manifest lives in `src/resources/functions/<functionCode>.json`. Call it from pages with `sdk.function.invoke(code, { input })`, from graph definitions with `function_call`, or from the runtime endpoint `/:appType/v1/functions/:code/invoke.json`. Direct runtime invocation defaults to app automation management permission; ordinary page callers must declare `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`). Prefer `export default async function(ctx, input) {}` for App Function source; the second argument is the invoke input and the same value is available as `ctx.input`. Current MVP exposes controlled helpers only and does not expose raw SQL or Redis. App Functions and trusted-node Automation scripts can call `ctx.files.readAsBase64` with an attachment from the current `ctx.formData`, or with a server-verified form record/field reference. This helper reads platform storage without a browser session, rejects arbitrary URLs and non-images, caps files at 10 MiB, and must be used without logging or persisting the Base64. App Functions can call `ctx.process.startFromExistingInstance`, `resolveCapabilities`, `resubmitTask`, `withdraw`, and `transferTask`; published trusted code may access resources in its current tenant/application, while workflow/task authorization, audit, event, replay, cross-app, and cross-tenant boundaries remain enforced. `resources` is optional mapping/audit metadata rather than an application-internal authorization list. Keep internal forms closed to direct user submit unless the business explicitly needs raw form submission; use `runtimeWrite.mode="function_only"` for function-only forms.
-
-For third-party credentials, use top-level metadata-only `secretRefs` plus `definitionJson.version="function_v2"` and `runtimeContractVersion="trusted_node_v2"`; read a declared value with `await ctx.secrets.get(name)` and call public business APIs through `ctx.utils.http`. Never use `process.env` for platform secrets. Values are managed with `openxiangda secret create|rotate --value-stdin --change <change> --profile <name>` and never appear in Git, build output, snapshots, plan diffs, logs, exceptions, or traces. Local tests may use `function test --secret-from-env logical=ENV` only; the value is passed to an isolated child over stdin and is never written to workspace/cache/state. For a Root App transaction, use exact-scope `resource publish function --only <code> --stage-only` and include its verified `stagedResource` in `release app-finalize`.
-
-For new AI-authored automations, prefer code-first `automation_code_ts` resources instead of visual v3 graph definitions. Put the source in `src/automations/<resourceCode>/index.ts`, define `definition.code.json` with `kind: "automation_code_ts"`, and provide `preview.json` for read-only frontend display. Use `ctx.logger.debug/info/warn/error(message, data?)` at every important step; OpenXiangda can inspect logs with `automation executions`, `automation logs`, and `automation diagnose`.
-
-For new AI-authored workflows where users do not need canvas editing, prefer compile-time `workflow.ts` using `openxiangda/workflow`. The CLI compiles it to v3 `definitionJson` and `preview.json`; the backend still runs the normal workflow engine for approval tasks, copy tasks, callback waits, branch advancement, and process records.
-
-Do not use JS_CODE for simple UI interactions, ordinary form validation, display-only page behavior, or logic that belongs in a normal React code page. For non-trivial backend logic, prefer JS_CODE V2 trusted Node scripts over large inline snippets. AI-authored JS_CODE source must be TypeScript:
-
-1. Put source in `src/js-code-nodes/<scriptCode>/index.ts`.
-2. Run `pnpm build-js-code --script <scriptCode>`. In a refreshed workspace this command typechecks only the selected entry and its transitive/shared/ambient dependencies, then bundles after validation passes; omit the selector only for an intentional full-workspace validation. Installed CLI resource commands independently use their packaged canonical scoped builder, including against standard older workspaces.
-3. In workflow or automation JSON, use:
-   ```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
-     }
-   }
-   ```
-
-The CLI requires `sourceFile.localPath` to point to TypeScript source in `src/js-code-nodes/<scriptCode>/index.ts`, `src/automations/<resourceCode>/index.ts`, or `src/functions/<functionCode>/index.ts`. During validate/create it runs `pnpm build-js-code --script <scriptCode>`, uploads the generated bundle to `/file/js-code-snapshot/upload`, verifies the server snapshot metadata, and replaces it with `{ bucketName, objectName, sha256, ... }`.
-
-The backend verifies the uploaded snapshot sha256 before execution, runs it in the trusted Node runtime, applies the node timeout (`30000` ms by default), stores console/runtime logs in the execution record, and writes the returned value to the node output and `variables.node_<nodeId>`.
-
-Inside the TypeScript script, prefer `export default async function (ctx) {}` or `module.exports = async (ctx) => {}`. The runtime exposes:
-
-- Context: `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`.
-- Data/process methods: `ctx.methods.queryOneData`, `queryManyData`, `getDataByFormInstanceId`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
-- Notification bridge: `ctx.notification.sendByType`, `batchSendByType`, `findConfig`, and `previewTemplate`. Declare templates in `src/resources/notifications/` before using custom `notificationType`.
-- Platform API bridge: `ctx.platform.api.get/post/put/patch/delete/request` for `/openxiangda-api/v1`; role helpers: `ctx.platform.roles.list/findByCode/addUsers/removeUser`.
-- Resource helpers: `ctx.resources.resolveForm/resolveDataView/resolveConnector`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.files.readAsBase64`, `ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask` for App Functions, `ctx.dataView.query/stats`, and `ctx.connector.call/invoke`.
-- Node runtime helpers: `require`, `process`, `Buffer`, `ctx.utils`, `ctx.utils.http`, and `ctx.console`.
-
-Example `function_call` node:
-
-```json
-{
-  "id": "call_summary",
-  "type": "function_call",
-  "data": {
-    "functionCode": "reservation_reminder_summary",
-    "input": { "scope": "today" },
-    "saveResponseTo": "summary"
-  }
-}
-```
-
-## Automation Flow
-
-New automation triggers must use `trigger_v2`.
-
-Use these v2 event sources and actions:
-
-- Form data: `event.source: "form_data"` with `submitted`, `updated`, or `deleted`.
-- Form field: `event.source: "form_field"`, `event.action: "changed"`, and `filters.fieldChange` with `fieldId` plus `changeType: "any" | "from_to" | "to_value" | "from_value"`.
-- Workflow task: `event.source: "workflow_task"` with `approved`, `rejected`, `returned`, `transferred`, or `cancelled`; use `filters.workflow.nodeId`, `operatorId`, `assigneeId`, and `previousAssigneeId` when needed.
-- Workflow process: `event.source: "workflow_process"` with `started`, `approved`, `rejected`, `terminated`, or `withdrawn`; set `filters.workflow.finalResult` for final outcomes.
-- Scheduled: `mode: "scheduled"` with `schedule.type: "fixed_time"` or `"form_date_field"`.
-
-The CLI passes `trigger_v2` through unchanged and fills root `appType`/`formUuid` from the active profile when omitted and resolvable, for example with `--form-code customer`. Do not put profile-specific IDs into reusable examples unless they are resolved from local workspace state.
-
-1. Create a trigger JSON and automation v3 definition JSON locally.
-2. Validate:
-   ```bash
-   openxiangda automation validate --trigger-json trigger.json --definition-json automation.json --strict --profile dev
-   ```
-3. Create and bind:
-   ```bash
-   openxiangda automation create notify_on_submit --name "提交后通知" --form-code customer --trigger-json trigger.json --definition-json automation.json --profile dev
-   ```
-4. Publish and enable:
-   ```bash
-   openxiangda automation publish notify_on_submit --profile dev
-   openxiangda automation enable notify_on_submit --profile dev
-   ```
-
-Use `automation disable` before risky edits. Published automations create a draft version when updated.
-
-## References
-
-- Best-practice architecture and status-flow boundary: `references/best-practices.md`
-- Workflow v3 JSON, semantic DSL, delayed-start cookbook, and capability action payloads: `references/workflow-v3.md`
-- Automation v3 JSON and triggers: `references/automation-v3.md`
-- Notification resources and runtime calls: `references/notifications.md`
-- API fields: `references/openxiangda-api.md`
-- Profile-isolated IDs: `references/workspace-state.md`

package/packages/sdk/bin/lowcode-workspace.mjs

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-import { main } from "../src/build-source/src/cli.mjs";
-
-await main(process.argv.slice(2));