openxiangda 1.0.116 → 1.0.118

package/README.md

@@ -315,6 +315,7 @@ AI-authored workflows can use compile-time SDK resources:
 - Local check: `openxiangda workflow compile src/workflows/<resourceCode>/workflow.ts --check`
 - Runtime operations: use `sdk.process.resolveCapabilities(...)` or `ProcessActionBar` / `ProcessTimeline` from `openxiangda/runtime/react` instead of hard-coded workflow buttons.
 - Delayed approval start: save a process-form draft without starting workflow via `StandardFormPage submitBehavior="save-draft"` or `sdk.form.create({ formUuid, data, saveAsDraft: true, startProcess: false })`; later call `sdk.process.startFromExistingInstance({ formUuid, formInstId })` or render `StandardFormPage` with `submitBehavior="start-existing-process"` to start approval in place. Do not create a second process instance and delete the draft.
+- AI workflow cookbook and action payload table: read `openxiangda-skills/references/workflow-v3.md` for the draft -> start existing instance -> return to initiator -> resubmit flow, and for operation payload details such as `approve` using process `instanceId` while `transfer` / `return` / `resubmit` use `taskId`.
 
 Resource and connector manifest guide: [docs/openxiangda-resources-and-connectors.md](docs/openxiangda-resources-and-connectors.md).
 

package/openxiangda-skills/SKILL.md

@@ -162,7 +162,7 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - Use JS_CODE for node-local cross-form data queries, create/update/batch update operations, process termination, platform API calls, external HTTP calls, and backend trigger orchestration. For logic that pages, automations, and workflows should reuse through a stable backend entry, prefer App Function. Do not use JS_CODE for simple UI interactions, ordinary form validation, or display-only page behavior.
 - For workflow/automation JS_CODE nodes, prefer V2 `runtimeMode: "trusted_node"`. AI-authored source must be TypeScript under `src/js-code-nodes/<scriptCode>/index.ts`, `src/automations/<resourceCode>/index.ts`, or `src/functions/<functionCode>/index.ts`. `pnpm build-js-code --script <scriptCode>` runs TypeScript validation before bundling, and `sourceFile.localPath` should point to the TS source; the CLI builds, uploads, and replaces it with snapshot metadata during validate/create.
 - Form permission group resources must have stable local codes. Use unique `code` values such as `ticket_reporter_view` and `ticket_repairer_view`; do not rely on the form code when one form has multiple groups.
-- Workflow resources should prefer `workflowFile` + `defineWorkflow` semantic DSL over hand-written raw JSON. For workflows bound by `formCode`, run `openxiangda workspace publish --form <formCode>` first so the process form schema/table is initialized, then run `openxiangda workflow compile <workflow.ts> --check` and `openxiangda resource publish --dry-run --profile <name>` before publish; use `sdk.process.resolveCapabilities(...)` or `ProcessActionBar` / `ProcessTimeline` from `openxiangda/runtime/react` for runtime buttons and timelines instead of hard-coded operation lists. For delayed approval start from an existing saved draft, first save without starting workflow via `StandardFormPage submitBehavior="save-draft"` or `sdk.form.create({ formUuid, data, saveAsDraft: true, startProcess: false })`; later use `sdk.process.startFromExistingInstance({ formUuid, formInstId })` or `StandardFormPage submitBehavior="start-existing-process"`; do not create a duplicate process instance and delete the draft.
+- Workflow resources should prefer `workflowFile` + `defineWorkflow` semantic DSL over hand-written raw JSON. For workflows bound by `formCode`, run `openxiangda workspace publish --form <formCode>` first so the process form schema/table is initialized, then run `openxiangda workflow compile <workflow.ts> --check` and `openxiangda resource publish --dry-run --profile <name>` before publish; use `sdk.process.resolveCapabilities(...)` or `ProcessActionBar` / `ProcessTimeline` from `openxiangda/runtime/react` for runtime buttons and timelines instead of hard-coded operation lists. For delayed approval start from an existing saved draft, first save without starting workflow via `StandardFormPage submitBehavior="save-draft"` or `sdk.form.create({ formUuid, data, saveAsDraft: true, startProcess: false })`; later use `sdk.process.startFromExistingInstance({ formUuid, formInstId })` or `StandardFormPage submitBehavior="start-existing-process"`; do not create a duplicate process instance and delete the draft. For custom workflow UI, return-to-initiator, resubmit, and action payload details, read `references/workflow-v3.md` sections `Cookbook: draft, start, return, resubmit` and `Capability action reference`.
 - Workflow resources can be created as drafts. After resource publish, verify `openxiangda workflow list --profile <name> --json` and run `openxiangda workflow publish <workflowCode> --profile <name>` until `isPublished: true` is visible. `workflow list` hides platform shell workflows with empty `resourceCode` by default; pass `--all` only when diagnosing raw platform rows.
 
 ## Subskills

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

@@ -110,6 +110,177 @@ For delayed approval start, do not submit a process form and then delete/recreat
 
 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

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

@@ -24,6 +24,7 @@ Create a workflow only when the scenario has **real approval semantics**: approv
 - ✅ 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.
+- ✅ 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`.
@@ -190,7 +191,7 @@ Use `automation disable` before risky edits. Published automations create a draf
 ## References
 
 - Best-practice architecture and status-flow boundary: `references/best-practices.md`
-- Workflow v3 JSON: `references/workflow-v3.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`

package/package.json

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

package/packages/sdk/dist/runtime/index.cjs

@@ -2560,6 +2560,33 @@ init_cjs_shims();
 
 // packages/sdk/src/runtime/core/fetch.ts
 init_cjs_shims();
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var isTransientFetchError = (error) => {
+  const anyError = error;
+  const message7 = String(anyError?.message || error || "").toLowerCase();
+  const causeCode = String(anyError?.cause?.code || "").toLowerCase();
+  return causeCode === "und_err_connect_timeout" || message7.includes("und_err_connect_timeout") || message7.includes("connect_timeout") || message7.includes("econnreset") || message7.includes("socket hang up") || message7.includes("network socket disconnected") || message7.includes("fetch failed");
+};
+var fetchWithTransientRetry = async (fetchImpl, input, init, options = {}) => {
+  if (!options.enabled) {
+    return fetchImpl(input, init);
+  }
+  const retries = Number.isFinite(Number(options.retries)) ? Number(options.retries) : 2;
+  const baseDelayMs = Number.isFinite(Number(options.baseDelayMs)) ? Number(options.baseDelayMs) : 250;
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      return await fetchImpl(input, init);
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retries || !isTransientFetchError(error)) {
+        throw error;
+      }
+      await sleep(Math.min(baseDelayMs * Math.pow(2, attempt), 2e3));
+    }
+  }
+  throw lastError;
+};
 var createBoundFetch = (fetchImpl) => {
   const baseFetch = fetchImpl || globalThis.fetch;
   return ((input, init) => baseFetch.call(globalThis, input, init));
@@ -28079,7 +28106,7 @@ var import_react162 = __toESM(require("react"));
 
 // node_modules/antd-mobile/es/utils/sleep.js
 init_cjs_shims();
-var sleep = (time) => new Promise((resolve) => setTimeout(resolve, time));
+var sleep2 = (time) => new Promise((resolve) => setTimeout(resolve, time));
 
 // node_modules/antd-mobile/es/components/pull-to-refresh/pull-to-refresh.js
 var classPrefix63 = `adm-pull-to-refresh`;
@@ -28152,7 +28179,7 @@ var PullToRefresh = (p) => {
         throw e2;
       }
       if (props.completeDelay > 0) {
-        yield sleep(props.completeDelay);
+        yield sleep2(props.completeDelay);
       }
       reset();
     });
@@ -34043,7 +34070,8 @@ function useProcessActions(options) {
             updateFormDataJson: requireValue(
               buildUpdateFormDataJson(input),
               "\u6682\u5B58\u6570\u636E\u4E0D\u80FD\u4E3A\u7A7A"
-            )
+            ),
+            comments: input.comments
           });
         } else if (operation.key === "resubmit") {
           await sdk.process.resubmitTask({
@@ -34333,6 +34361,12 @@ var normalizeMethod2 = (method4) => {
   const value = String(method4 || "get").toUpperCase();
   return ["GET", "POST", "PUT", "DELETE", "PATCH"].includes(value) ? value : "GET";
 };
+var shouldRetryTransportRequest = (payload) => {
+  const method4 = normalizeMethod2(payload?.method);
+  if (method4 === "GET") return true;
+  const path = String(payload?.path || "").split("?")[0];
+  return method4 === "POST" && path === "/workflow/capabilities/resolve";
+};
 var normalizeCssIsolation2 = (value) => {
   if (value === "namespace" || value === "shadow" || value === "none") {
     return value;
@@ -34393,11 +34427,13 @@ var createBrowserPageBridge = (options = {}) => {
         body = JSON.stringify(payload.body);
       }
     }
-    const response = await fetchImpl(url2, {
+    const response = await fetchWithTransientRetry(fetchImpl, url2, {
       method: normalizeMethod2(payload.method),
       headers,
       body,
       credentials: "include"
+    }, {
+      enabled: shouldRetryTransportRequest(payload)
     });
     return parseJsonResponse(response);
   };