openxiangda 1.0.264 → 2.0.0-alpha.2

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

@@ -1,441 +0,0 @@
-# Workflow V3 Reference
-
-Workflow definitions are v3 graph JSON objects saved by `openxiangda workflow create`.
-
-AI-authored workflows should prefer the compile-time TypeScript DSL. The SDK compiles local `workflow.ts` into the current v3 graph JSON, so the backend still uses the existing workflow engine for approval tasks, copy tasks, return/resubmit, transfer, callback waits, branch advancement, operation logs, notifications, and process completion events. Write raw JSON only when repairing a pulled designer definition.
-
-Example `src/workflows/expense_approval/workflow.ts`:
-
-```ts
-import { defineWorkflow } from "openxiangda/workflow";
-
-export default defineWorkflow({
-  build(flow) {
-    const start = flow.start();
-    const approve = flow.approval("manager_approval", {
-      label: "主管审批",
-      approverType: "ext_target_approval",
-      approvals: ["USER_MANAGER"],
-      approvalNames: ["主管"],
-      multiApprove: "or",
-      actions: [
-        flow.action.approve("通过"),
-        flow.action.reject("驳回"),
-        flow.action.transfer(),
-        flow.action.return(),
-      ],
-      returnPolicy: { scopeType: "initiator", resubmitMode: "resume_current" },
-      fieldPermissions: [{ fieldId: "amount", fieldBehavior: "READONLY" }],
-    });
-    const sync = flow.functionCall("sync_budget", {
-      functionCode: "sync_budget",
-      input: { amount: "{{form.amount}}" },
-      saveResponseTo: "budgetResult",
-    });
-    const copy = flow.copy("copy_finance", {
-      label: "抄送财务",
-      approverType: "ext_target_approval",
-      approvals: ["USER_FINANCE"],
-      approvalNames: ["财务"],
-    });
-    const end = flow.end();
-    flow.sequence(start, approve, sync, copy, end);
-  },
-});
-```
-
-For compact AI-authored drafts, `flow.define` is also exported. It accepts
-declarative node and edge helpers, then compiles to the same v3 JSON:
-
-```ts
-import { flow } from "openxiangda/workflow";
-
-export default flow.define({
-  name: "费用审批",
-  formUuid: "FORM_UUID",
-  nodes: [
-    flow.start("start"),
-    flow.approval("manager_approval", {
-      label: "主管审批",
-      assignees: [flow.assignee.initiator()],
-      actions: [
-        flow.action.approve("通过"),
-        flow.action.returnToInitiator(),
-        flow.action.transfer(),
-      ],
-      fieldPermissions: { amount: "readonly" },
-    }),
-    flow.functionCall("sync_budget", {
-      functionName: "sync_budget",
-      input: { amount: "${amount}" },
-    }),
-    flow.end("end"),
-  ],
-  edges: [
-    flow.connect("start", "manager_approval"),
-    flow.connect("manager_approval", "sync_budget"),
-    flow.connect("sync_budget", "end"),
-  ],
-});
-```
-
-Resource manifest:
-
-```json
-{
-  "code": "expense_approval",
-  "formCode": "expense",
-  "workflowFile": "../../../workflows/expense_approval/workflow.ts",
-  "definitionFile": "definition.v3.json",
-  "previewFile": "preview.json",
-  "publish": true
-}
-```
-
-During `openxiangda resource validate`, `resource plan`, and `resource publish --dry-run`, the CLI compiles `workflowFile` without writing generated files or platform resources. During real `openxiangda resource publish`, the CLI compiles `workflowFile`, writes `definitionFile` and `previewFile` when configured, sends v3 `definitionJson` to the backend, and stores the preview in `viewJson` for read-only frontend display.
-
-Compile locally before publishing:
-
-```bash
-openxiangda workflow compile src/workflows/expense_approval/workflow.ts --check
-openxiangda workflow compile src/workflows/expense_approval/workflow.ts --stdout
-openxiangda workflow compile src/workflows/expense_approval/workflow.ts \
-  --out-definition src/resources/workflows/expense_approval/definition.v3.json \
-  --out-preview src/resources/workflows/expense_approval/preview.json
-```
-
-Runtime pages should not guess buttons. Use `sdk.process.resolveCapabilities(...)` or the React helpers from `openxiangda/runtime/react`: `useProcessCapabilities`, `useProcessActions`, `ProcessActionBar`, `ProcessTimeline`, `ProcessPreviewPanel`, and `InitiatorApproverSelector`. The capability protocol returns `visible`, `enabled`, `disabledReason`, `paramsSchema`, `uiSchema`, return candidates, field permissions, and refresh hints for operations such as approve, reject, transfer, return, save, withdraw, resubmit, callback, retryException, and adminTransfer.
-
-Runtime todo, done, cc, and initiated lists should use `sdk.workCenter.listItems({ boxType })` plus `sdk.workCenter.getStats()`. These APIs return the current user's projected work-center items with pagination, app/form filters, status/result filters, `actionUrl`, `formUuid`, `formInstanceId`, `taskId`, and node/title snapshots. Do not query workflow operation logs, automation logs, or raw process task tables for end-user task-center pages.
-
-For delayed approval start, do not submit a process form and then delete/recreate records. Save the process-form instance without starting workflow via `StandardFormPage submitBehavior="save-draft"` or `sdk.form.create({ formUuid, data, saveAsDraft: true, startProcess: false })`. Later start approval on that same `formInstId` with `sdk.process.startFromExistingInstance({ formUuid, formInstId })` or `StandardFormPage submitBehavior="start-existing-process"`.
-
-For return-to-initiator workflows, prefer `returnPolicy: { scopeType: "initiator", resubmitMode: "resume_current" }` or `flow.action.returnToInitiator()`. The runtime capabilities protocol exposes `resubmit` only on pending `originator_return` tasks. If a user returns to a previous approval node, continuing the flow is a normal `approve` action on that returned approval task.
-
-## Cookbook: draft, start, return, resubmit
-
-Use this pattern when the business user creates real data first and starts approval later from the same form instance. Do not copy the draft into a new process record.
-
-1. Define a semantic workflow with an approval node that can save, return to the initiator, and resume the current approval after resubmission:
-
-   ```ts
-   import { defineWorkflow } from "openxiangda/workflow";
-
-   export default defineWorkflow({
-     build(flow) {
-       const start = flow.start();
-       const approval = flow.approval("manager_approval", {
-         label: "Manager approval",
-         approverType: "ext_target_approval",
-         approvals: ["USER_MANAGER"],
-         approvalNames: ["Manager"],
-         actions: [
-           flow.action.approve("Approve"),
-           flow.action.reject("Reject"),
-           flow.action.save("Save"),
-           flow.action.transfer("Transfer"),
-           flow.action.returnToInitiator("Return to initiator", {
-             resubmitMode: "resume_current",
-           }),
-         ],
-         returnPolicy: {
-           scopeType: "initiator",
-           resubmitMode: "resume_current",
-         },
-       });
-       flow.sequence(start, approval, flow.end());
-     },
-   });
-   ```
-
-2. Publish the process form before publishing the workflow resource. The form publish initializes the process-form storage table used by delayed starts:
-
-   ```bash
-   openxiangda workspace publish --form expense --profile dev
-   openxiangda workflow compile src/workflows/expense_approval/workflow.ts --check
-   openxiangda resource publish --profile dev --dry-run
-   openxiangda resource publish --profile dev
-   openxiangda workflow list --profile dev --json
-   ```
-
-   If the target workflow is a draft after resource publish, run `openxiangda workflow publish <workflowCode> --profile dev` until `isPublished: true` is visible.
-
-3. Save the process-form record without starting approval:
-
-   ```tsx
-   await sdk.form.create({
-     formUuid,
-     data: draftValues,
-     saveAsDraft: true,
-     startProcess: false,
-   });
-   ```
-
-   Standard form pages can use the built-in behavior:
-
-   ```tsx
-   <StandardFormPage
-     schema={schema}
-     mode="submit"
-     submitBehavior="save-draft"
-   />
-   ```
-
-4. Later, start approval on the same `formInstId`. The current operator becomes the workflow initiator by default:
-
-   ```tsx
-   await sdk.process.startFromExistingInstance({
-     formUuid,
-     formInstId,
-     updateFormDataJson: JSON.stringify(finalValues),
-     submissionDepartmentId,
-     selectedApprovers,
-   });
-   ```
-
-   Standard form pages can start approval in place:
-
-   ```tsx
-   <StandardFormPage
-     schema={schema}
-     mode="submit"
-     formInstanceId={formInstId}
-     submitBehavior="start-existing-process"
-   />
-   ```
-
-5. In a custom detail page, render operations from capabilities instead of hard-coded buttons:
-
-   ```tsx
-   import {
-     ProcessActionBar,
-     ProcessTimeline,
-     useProcessCapabilities,
-   } from "openxiangda/runtime/react";
-
-   export function ContractApprovalPanel({ formUuid, formInstId, getValues }) {
-     const capabilityParams = { formUuid, formInstId };
-     const process = useProcessCapabilities(capabilityParams);
-
-     return (
-       <>
-         <ProcessActionBar
-           capabilities={process.capabilities}
-           formUuid={formUuid}
-           getFormValues={getValues}
-           onRefreshCapabilities={process.refresh}
-         />
-         <ProcessTimeline capabilities={process.capabilities} />
-       </>
-     );
-   }
-   ```
-
-6. Return-to-initiator flow:
-
-   - Approver executes the `return` operation. For initiator return, the return candidate normally has `nodeId: "__originator__"` or equivalent initiator metadata.
-   - Initiator resolves capabilities for the same `formInstId` or returned `taskId`; the current task should be `nodeType: "originator_return"`.
-   - Initiator executes `resubmit` with updated form data.
-   - With `resubmitMode: "resume_current"`, the engine restores the source approval task. The next capabilities response should show an approval task again, often with `taskKind: "resume"`.
-   - The approver then uses the normal `approve` action. Final form search snapshots should show `processInstanceStatus: "completed"` and `approvalResult: "approved"`.
-
-## Capability action reference
-
-Always call `sdk.process.resolveCapabilities(...)` first. It returns instance state, current task, field permissions, timeline, and `operations`. Each operation includes `key`, `label`, `visible`, `enabled`, `disabledReason`, `taskId`, `instanceId`, `nodeId`, `paramsSchema`, `uiSchema`, `returnableNodes`, and `refreshHints`. Render only operations where `visible !== false`; if `enabled === false`, show `disabledReason`.
-
-Use `paramsSchema` and `uiSchema` as the source of truth for dialogs. Do not hard-code which operation needs a modal or which fields are required.
-
-| Operation | When it appears | SDK method | Required IDs | Common params |
-| --- | --- | --- | --- | --- |
-| `startProcess` | Saved process-form instance that has no workflow instance yet | `sdk.process.startFromExistingInstance` | `formUuid`, `formInstId` / `formInstanceId` | `updateFormDataJson`, `submissionDepartmentId`, `selectedApprovers`, `initiatorSelectedApprovers` |
-| `approve` | Current user has a pending approval task | `sdk.process.approve` | `instanceId` (process instance ID, not task ID) | `comments`, `updateFormDataJson` |
-| `reject` | Current user can reject the pending approval task | `sdk.process.reject` | `instanceId` (process instance ID, not task ID) | `comments`, `updateFormDataJson` |
-| `save` | Current task allows editing without advancing the workflow | `sdk.process.saveTask` | `instanceId`, `formUuid` | `updateFormDataJson`, `comments` |
-| `transfer` | Current user can transfer the current task | `sdk.process.transferTask` | `taskId` | `newAssignee`, `reason` |
-| `return` | Current approval task has return candidates | `sdk.process.returnTask` | `taskId`, `targetNodeId` | `reason`; choose `targetNodeId` from `operation.returnableNodes` |
-| `withdraw` | Initiator can withdraw a running process | `sdk.process.withdraw` | `instanceId` | `reason` |
-| `resubmit` | Initiator is handling an `originator_return` task | `sdk.process.resubmitTask` | `taskId`, `formUuid` | `updateFormDataJson`, `comments`, `selectedApprovers`, `initiatorSelectedApprovers` |
-| `callback` | Process is waiting on a callback task | `sdk.process.triggerCallback` | `taskId` | `payload` |
-| `retryException` | Process instance is in exception state and user can retry | `sdk.process.retryException` | `instanceId` | none |
-| `adminTransfer` | App/platform admin can reassign a task | `sdk.process.adminTransferTask` | `taskId` | `newAssignee`, `reason` |
-
-Recommended custom dispatcher:
-
-```ts
-const caps = await sdk.process.resolveCapabilities({ formUuid, formInstId });
-const op = caps.result.operations.find((item) => item.key === "return");
-if (!op?.enabled) throw new Error(op?.disabledReason || "return unavailable");
-
-await sdk.process.returnTask({
-  taskId: String(op.taskId),
-  targetNodeId: String(op.returnableNodes?.[0]?.nodeId),
-  reason: "Need more information",
-});
-```
-
-After every successful action, refresh the surfaces listed by `operation.refreshHints`. In most pages this means reloading capabilities, process basic/progress, timeline, and form data. `ProcessActionBar` does this when `onRefreshCapabilities` or `capabilityParams` is provided.
-
-Troubleshooting:
-
-- If `approve` or `reject` returns "process instance not found", check that the request used `instanceId`, not `taskId`.
-- If `return` has no valid target, inspect `operation.returnableNodes` and the workflow node `returnPolicy`; do not invent a node ID.
-- If `resubmit` is missing, make sure the active task is `originator_return`; a task returned to a previous approval node continues with normal `approve`.
-- If a workflow created by `resource publish` is not active, run `openxiangda workflow list --profile <name> --json` and publish the workflow until `isPublished: true`.
-- If `workflow list` shows a row with empty `resourceCode`, it is a platform shell workflow. The default list hides those rows; use `--all` only for raw diagnostics.
-
-Minimum shape:
-
-```json
-{
-  "version": "v3",
-  "nodes": [
-    { "id": "start", "type": "start", "data": { "label": "开始" } },
-    { "id": "approve", "type": "approval", "data": { "label": "审批" } },
-    { "id": "end", "type": "end", "data": { "label": "结束" } }
-  ],
-  "edges": [
-    { "id": "e1", "source": "start", "target": "approve" },
-    { "id": "e2", "source": "approve", "target": "end" }
-  ],
-  "flowConfig": {}
-}
-```
-
-Rules:
-
-- `nodes` and `edges` must be arrays.
-- `version` must be `v3`.
-- Publishing requires one `start` node and at least one `end` node.
-- Each node needs `id`, `type`, and object `data`.
-- Edges must reference existing node IDs.
-- Keep live platform IDs out of the JSON when possible. Resolve `formUuid` and `workflowId` through CLI state.
-- JS_CODE V2 supports trusted Node execution. For AI/admin logic use `runtimeMode: "trusted_node"`.
-
-Supported node types:
-
-- `start`
-- `approval`
-- `condition`
-- `condition_branch`
-- `end`
-- `copy`
-- `js_code`
-- `branch`
-- `data_retrieve_single`
-- `data_retrieve_batch`
-- `data_create`
-- `data_update`
-- `loop_container`
-- `connector_call`
-- `function_call`
-- `callback_wait`
-- `work_notification`
-- `dingtalk_card`
-
-## JS_CODE V2
-
-Workflow JS_CODE runs on the backend when the process reaches the `js_code` node. Use it before or after approval nodes, in branches, or before ending a process when the workflow needs server-side side effects such as cross-form synchronization, audit record creation, external API calls, or terminating a related process. Do not use it for frontend-only behavior.
-
-Inline:
-
-```json
-{
-  "id": "calc",
-  "type": "js_code",
-  "data": {
-    "label": "计算",
-    "runtimeMode": "trusted_node",
-    "sourceType": "inline",
-    "code": "const crypto = require('crypto'); variables.hash = crypto.createHash('sha256').update('x').digest('hex'); return variables.hash;",
-    "timeout": 30000
-  }
-}
-```
-
-File snapshot:
-
-```json
-{
-  "id": "sync_customer",
-  "type": "js_code",
-  "data": {
-    "label": "同步客户",
-    "runtimeMode": "trusted_node",
-    "sourceType": "file_snapshot",
-    "scriptCode": "sync_customer",
-    "sourceFile": {
-      "localPath": "src/js-code-nodes/sync_customer/index.ts"
-    },
-    "timeout": 30000
-  }
-}
-```
-
-AI-authored JS_CODE source must be TypeScript under `src/js-code-nodes/<scriptCode>/index.ts`. When validating or creating, the CLI runs `pnpm build-js-code --script <scriptCode>`, which typechecks only the selected entry plus its transitive/shared/ambient dependencies, bundles to `dist/js-code-nodes/<scriptCode>/index.cjs`, uploads the bundle, and replaces `sourceFile.localPath` with immutable snapshot metadata. An intentionally unscoped build retains full-workspace TypeScript validation. The backend verifies snapshot `sha256`, 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>`.
-
-For reusable backend logic that should be shared by pages, automations, and workflows, prefer an App Function under `src/functions/<functionCode>/index.ts` plus `src/resources/functions/<functionCode>.json`. Workflow graphs that support App Function nodes can call it with:
-
-```json
-{
-  "id": "call_summary",
-  "type": "function_call",
-  "data": {
-    "functionCode": "reservation_reminder_summary",
-    "input": { "scope": "process" },
-    "saveResponseTo": "summary"
-  }
-}
-```
-
-Use JS_CODE V2 when the script is local to one workflow node.
-
-Scripts can export `export default async function (ctx) {}` or `module.exports = async (ctx) => {}`. The runtime exposes `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, `ctx.resources`, `ctx.form`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, `ctx.platform.roles.*`, `ctx.platform.api.*`, `ctx.utils`, `require`, `process`, and `Buffer`. App Functions additionally expose `ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`; trusted code is scoped to its current tenant/application and reuses the real operator's official workflow permission, operation-log, event, idempotency, and replay paths. Per-resource declarations are optional mapping/audit metadata, not an application-internal authorization list. Prefer `ctx.resources.resolveForm/resolveDataView/resolveConnector`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.dataView.query/stats`, `ctx.connector.call/invoke`, and `ctx.platform.roles.findByCode/addUsers/removeUser` for platform-side work. Use `ctx.organization.departments.*` and `ctx.organization.accounts.*` only for intentional organization-management flows; the real operator/audit actor must hold `app:organization:manage`. App Function and trusted-node form writes are backend operations, not direct page-user submit access; keep internal forms closed to raw user submission unless the business requires it. Raw `ctx.platform.api.*` calls return HTTP response plus platform envelope. Legacy data/process bridge methods remain available as `ctx.methods.queryOneData/queryManyData/getDataByFormInstanceId/updateOneData/updateDataByFormInstanceId/updateManyData/createOneData/terminateProcess/getAllParentDepartments`.
-
-Example `src/js-code-nodes/sync_customer/index.ts`:
-
-```ts
-export default async function syncCustomer(ctx) {
-  const current = ctx.formData?.current || {};
-  const appType = ctx.app.appType;
-  const customerNo = current.customer_no;
-
-  const customer = await ctx.methods.queryOneData(appType, "FORM_CUSTOMER", {
-    customer_no: customerNo,
-  });
-
-  if (customer) {
-    await ctx.methods.updateOneData(
-      appType,
-      "FORM_CUSTOMER",
-      { customer_no: customerNo },
-      { last_approved_at: new Date().toISOString() }
-    );
-  }
-
-  const log = await ctx.methods.createOneData(appType, "FORM_SYNC_LOG", {
-    source: "workflow",
-    customer_no: customerNo,
-    result: customer ? "updated" : "missing",
-  });
-
-  return {
-    customerFound: Boolean(customer),
-    logId: log?.formInstanceId || log?.id,
-  };
-}
-```
-
-Field permission config lives in `flowConfig` by node ID:
-
-```json
-{
-  "flowConfig": {
-    "approve": [
-      { "fieldId": "amount", "fieldBehavior": "READONLY" },
-      { "fieldId": "remark", "fieldBehavior": "NORMAL" }
-    ]
-  }
-}
-```
-
-Allowed `fieldBehavior` values: `NORMAL`, `READONLY`, `HIDDEN`.

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

@@ -1,115 +0,0 @@
-# Workspace State
-
-OpenXiangda durable project bindings live in `.openxiangda/state.json`. Volatile release execution, candidate, deployment, and recovery progress lives under the private `.openxiangda/releases/` journal and must not be copied into the durable ID map.
-
-Tokens never belong in the project. User tokens live in `~/.openxiangda/profiles.json`. Shared workspace env values such as `APP_OSS_*` live in `~/.openxiangda/.env` by default, while project `.env` is only a local override.
-
-## Shape
-
-```json
-{
-  "version": 1,
-  "profiles": {
-    "dev": {
-      "baseUrl": "https://dev-lowcode.example.com/service",
-      "appType": "APP_DEV",
-      "resources": {
-        "forms": {
-          "customer": {
-            "formUuid": "FORM_XXX"
-          }
-        },
-        "pages": {
-          "dashboard": {
-            "pageId": "PAGE_XXX",
-            "routeKey": "dashboard",
-            "legacyFormUuid": "FORM_LEGACY_PAGE"
-          }
-        },
-        "workflows": {},
-        "automations": {},
-        "menus": {},
-        "roles": {},
-        "connectors": {},
-        "dataViews": {
-          "ticket_with_customer": {
-            "dataViewId": "DV_XXX",
-            "materializedViewName": "mv_dv_abc123",
-            "status": "active"
-          }
-        },
-        "notifications": {
-          "templates": {},
-          "typeConfigs": {}
-        },
-        "pagePermissionGroups": {},
-        "formPermissionGroups": {},
-        "formSettings": {}
-      }
-    }
-  }
-}
-```
-
-Environment-managed workspaces add a logical application and target-specific bindings. The legacy `profiles` map may remain for compatibility, but managed commands resolve only the selected target:
-
-```json
-{
-  "version": 1,
-  "logicalApp": {
-    "id": "ENVSET_UUID",
-    "code": "instrument-sharing",
-    "name": "大型仪器共享"
-  },
-  "currentTarget": "preproduction",
-  "targets": {
-    "preproduction": {
-      "profile": "hgy",
-      "environmentId": "PRE_ENV_UUID",
-      "kind": "preproduction",
-      "appType": "APP_PRE",
-      "revision": 4,
-      "sideEffectPolicy": {
-        "notifications": "tester_allowlist",
-        "notificationAllowlist": [],
-        "organizationWrites": "deny",
-        "scheduledAutomations": "disabled",
-        "externalWrites": "allowlist",
-        "payments": "deny",
-        "publicIndexing": "deny",
-        "environmentBanner": true
-      },
-      "resources": {}
-    },
-    "production": {
-      "profile": "hgy",
-      "environmentId": "PROD_ENV_UUID",
-      "kind": "production",
-      "appType": "APP_PROD",
-      "resources": {}
-    }
-  }
-}
-```
-
-## Rules
-
-- Profile is the deployment boundary.
-- For an environment-managed logical application, the selected target is the deployment boundary inside the profile. `preproduction` and `production` own independent appType, resource IDs, Release Heads, data, and side-effect policy. Their volatile deployment progress is isolated in `.openxiangda/releases/targets/`.
-- `baseUrl` is the backend API base. On standard private deployments it is `<origin>/service`; management pages use `/platform`, and app runtime pages use `/view`.
-- Local state is authoritative for app binding. If a workspace has no `appType` for the target profile, create a new app/workspace with `openxiangda workspace init <dir> --profile <name> --app-name "应用名称"`.
-- Do not search platform apps or reuse similar names unless the user explicitly asks to reuse an existing app or provides an `appType`.
-- Local resource keys are logical codes.
-- Live IDs and lightweight runtime aliases are nested under the profile that produced them.
-- `resources.dataViews` is keyed by data view `code` and stores only profile-local platform metadata such as `dataViewId`, `materializedViewName`, and last known `status`.
-- The stored DataView `status` is observational: managed staging legitimately moves it between `draft` and `active`. Candidate binding validation ignores only that field, including for older sealed candidates, while keeping `dataViewId`, `materializedViewName`, `storageMode`, and all non-DataView status fields strict.
-- Data view definitions, refresh config, permissions, and source `formCode` references belong in `src/resources/data-views/*.json`, not in state.
-- Do not store business configuration or secrets in `.openxiangda/state.json`; store those in `src/resources/`.
-- CLI writes use a lock, a three-way merge at profile/resource-key granularity, and fsync + atomic rename. Concurrent writes to different profiles or logical resource keys are preserved; competing writes to the same field fail with `OPENXIANGDA_STATE_CONFLICT` and must be retried from a freshly loaded state.
-- This protects the ID map from truncation/lost updates. Concurrent development still uses separate Git worktrees/branches; `.openxiangda/worktree-owner.json` binds one worktree to one active `CODEX_THREAD_ID` and blocks a second task at SDD context/publish time.
-- A prod publish must not read dev IDs.
-- Never copy target resource bindings. Use `openxiangda environment use <target>` or pass `--environment <target>` and let the CLI populate that target from its own deployment.
-- Managed targets cannot use direct `release publish`; use `release ship`. The normal first invocation prepares preproduction and stops, while a later `--confirm-production` promotes the same sealed candidate. Explicitly authorized emergencies may place `--confirm-production` on the first invocation to run both ordered phases in one command. The candidate freezes stable environment/resource bindings and target-specific Runtime artifacts, and both server deployments must finish as `succeeded`. A frozen baseline-adoption intent is reused from `ship.json`; a different repeated intent fails before a request. Human acceptance is recommended and may be recorded with optional `--acceptance-note`.
-- In a managed workspace with multiple targets, `function invoke` must include `--environment <target>` and reports the resolved target on stderr before sending the request.
-- Change a single target's side-effect policy with `openxiangda environment policy update <kind|id> --side-effect-policy-json <JSON|file> --reason "..." --dry-run`, inspect the exact diff, then repeat without `--dry-run`. The write uses the server revision as CAS and updates local `revision`; it does not swap roles or alter Release Heads. Omitted fields are preserved unless `--full-replace` is explicit, and production additionally requires `--confirm-production`.
-- Before publishing to another platform, run `openxiangda workspace bind --profile <name> --app-type <APP_XXX>`.

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

@@ -1,118 +0,0 @@
----
-name: openxiangda-app
-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
-
-## 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
-
-Always start from the current profile and workspace binding:
-
-```bash
-openxiangda env --profile <name>
-openxiangda auth status --profile <name>
-```
-
-If the workspace is not bound:
-
-```bash
-openxiangda workspace init ./my-app-workspace --profile <name> --app-name "应用名称"
-cd ./my-app-workspace
-pnpm install
-```
-
-For new Phase 6 React SPA apps, use the standard React application template:
-
-```bash
-openxiangda workspace init ./my-react-app \
-  --profile <name> \
-  --app-name "应用名称" \
-  --runtime react-spa
-cd ./my-react-app
-pnpm install
-pnpm dev
-```
-
-React SPA workspaces use React Router, Tailwind CSS, `OpenXiangdaProvider`
-from `openxiangda/runtime/react`, and resources under `src/resources/`.
-Do not use old `isRenderNav`, app-shell, or workbench page parameters inside
-React SPA routes.
-
-Publish React SPA apps with:
-
-```bash
-openxiangda resource publish --profile <name>
-openxiangda runtime deploy --profile <name>
-```
-
-`runtime deploy` builds and activates the app-level SPA release for `/view/:appType/*`. It uploads `dist/` through staged multipart file uploads by default; use `--upload-mode legacy-json` only as an older-server fallback.
-Publish React SPA forms separately with `openxiangda workspace publish --form <formCode>`;
-with `runtimeMode: "react-spa"` this is schema-only and does not require OSS.
-
-Bind to an existing app only when the user explicitly provides `appType` or asks to reuse an existing platform app:
-
-```bash
-openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXX
-openxiangda workspace bind --profile <name> --app-type APP_XXX
-```
-
-For menu work:
-
-```bash
-openxiangda menu list --profile <name>
-openxiangda menu create main --name "主菜单" --type nav --profile <name>
-openxiangda menu create customer-entry --name "客户信息" --type receipt --form-code customer --profile <name>
-```
-
-If the user explicitly asks to create an app without initializing a workspace:
-
-```bash
-openxiangda app create "应用名称" --profile <name>
-openxiangda app create "React应用名称" --profile <name> --runtime react-spa
-openxiangda workspace bind --profile <name> --app-type APP_XXX
-```
-
-## Rules
-
-- Never ask for AK/SK.
-- Always pass `--profile` for publish or cross-platform operations.
-- Local `.openxiangda/state.json` is authoritative. If the user starts from a new empty directory or the workspace has no app binding, create a new app with `openxiangda workspace init <dir> --profile <name> --app-name "应用名称"`.
-- Do not search platform apps or reuse similar app names unless the user explicitly asks to reuse an existing app or gives an `appType`.
-- Store platform-specific IDs only in `.openxiangda/state.json`.
-- Use logical local codes for forms, pages, workflows, automations, and menus.
-- Before scaffolding a new business app, read `references/best-practices.md` and pick an architecture from the initialized `examples/best-practices/` catalog. Do not generate a large single-file app page when a template pattern already covers the scenario.
-- For Phase 6 React SPA apps, use `--runtime react-spa`. The generated app owns routing/layouts/menus with React Router and Tailwind CSS; platform permissions still come from backend runtime bootstrap and route checks.
-- React SPA form publish is schema-only by default. Do not add OSS credentials or old embedded form bundles unless explicitly maintaining legacy compatibility with `--legacy-form-bundle`.
-- When publishing after app edits, prefer targeted commands (`workspace publish --changed --dry-run`, then `--changed`, `--page`, `--form`, or `--only`). Do not publish all forms/pages just because one page changed.
-- Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` before changing an existing app.
-
-## Resource State
-
-Read `references/workspace-state.md` when changing `.openxiangda/state.json`.
-
-Read `references/openxiangda-api.md` when exact endpoint fields are needed.
-
-Read `references/resource-manifest-cheatsheet.md` before creating shared resources such as data views, connectors, notifications, App Functions, workflows, automations, permissions, settings, or menus.
-
-Read `references/architecture-patterns.md` to understand the overall app structure (how forms, pages, menus, workflows, and permissions compose into an app, and the recommended `src/forms` / `src/pages` layout) before scaffolding or restructuring an app workspace.
-
-Read `references/best-practices.md` before implementing app-level patterns such as status lifecycles, role governance, PC/mobile portals, high-performance data management pages, workflow boundaries, and automation.