openxiangda 1.0.222 → 1.0.224

package/README.md

@@ -96,11 +96,13 @@ Use `environment policy update <kind|id>` when only one environment's side-effec
 
 `resource plan` and `resource publish --dry-run` run behind a strict GET/HEAD-only HTTP guard. If a read receives HTTP 401, the command fails with `READ_ONLY_AUTH_REQUIRED` and never calls the token refresh POST from inside the plan. Run `openxiangda auth refresh --profile <name>` (or log in again) before retrying; a plan must not mutate auth state or platform resources.
 
-For Function/Automation plans, `formFieldContracts` checks statically declared
-Form filter/order fields against frozen online Form schemas. A missing binding
-or field makes publish fail before lease/write; dynamic field names are checked
-again by the platform before SQL and return `FORM_FIELD_NOT_FOUND` instead of a
-database-column error.
+For Function/Automation plans, `formFieldContracts` resolves statically
+referenced Forms through the target application's registry and checks
+filter/order fields against frozen online Form schemas. A missing application
+mapping or field makes publish fail before lease/write; repeating every source
+reference in every Function manifest is not required. Dynamic field names are
+checked again by the platform before SQL and return `FORM_FIELD_NOT_FOUND`
+instead of a database-column error.
 
 React SPA workspaces publish their frontend with `openxiangda runtime deploy`. Every finalized Runtime release is built from a clean, committed Git `HEAD`; the CLI freezes `sourceRevision`, the current active release, and its source revision before any build/upload. Deploy fails with `RUNTIME_SOURCE_BASE_DIVERGED` when its `HEAD` does not descend from the online Runtime source, including with `--no-activate`, so an old isolated worktree cannot stage and later activate a silent rollback. `.openxiangda/`, `openspec/`, `dist/`, and other pure generated/governance/state paths do not make the source dirty, but `--no-build` cannot bypass the lineage gate. An intentional rollback requires `--allow-runtime-rollback --reason "<at least 8 characters>"`, which is persisted for audit and never bypasses dirty/non-Git checks.
 
@@ -506,7 +508,7 @@ const PublicAccessError = ({ error }: { error: { message?: string } }) => (
 
 多表只读查询和固定口径统计优先声明 `src/resources/data-views/*.json` 数据视图，而不是在页面里手写多次单表查询再拼数据。默认 `storageMode: "materialized"` 会创建 PostgreSQL materialized view，适合读多写少和可接受刷新延迟的列表/报表；`storageMode: "live"` 每次查询实时编译逻辑视图，适合强实时但数据量可控的复杂查询。`viewType: "aggregate"` 是统计聚合视图，适合按客户、状态、月份等维度聚合 count/sum/avg/min/max。发布时 CLI 会把 `formCode` 解析为当前 profile 的 `formUuid`；页面通过 `sdk.dataView.query(code, params)` 查询行级视图，通过 `sdk.dataView.stats(code, params)` 查询聚合视图，也可以用 `sdk.dataSource.run()` 路由 `dataView.query` / `dataView.stats`。materialized 模式应为常用筛选、排序、统计维度和时间桶声明 `indexes`，并确认用户能接受的刷新延迟；live 模式忽略 `indexes`，不需要刷新。
 
-后端业务逻辑优先声明为 App Function：源码放在 `src/functions/<functionCode>/index.ts`，资源 manifest 放在 `src/resources/functions/<functionCode>.json`。函数运行在 trusted_node 中，通过 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.organization`、`ctx.platform.roles`、`ctx.platform.api` 等受控 API 访问平台能力；自动化、流程和运行时接口都可以调用同一个 function。`ctx.process` 复用正式工作流服务，以真实运行时 operator 执行，并严格限制在当前应用及 Function `resources.forms` 已绑定的流程表单；流程实例、任务授权、操作日志、事件和 replay 语义与 PageSdk 后端接口一致。角色查询和角色成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`，底层 `ctx.platform.api` 返回 HTTP 包装和平台 envelope，需要业务代码自行解包。运行时页面调用会在 `ctx.operator`、`ctx.currentUser`、`ctx.permissions` 中注入可信的 `roleCodes`、`currentRoleCode`、`hasFullAccess`、`isAppAdmin`、`isPlatformAdmin`，敏感动作必须读取这些服务端上下文做授权，不要信任页面 input 里传入的角色字段。`ctx.form.createOne/updateOne/updateById` 是后端受控写入，授权边界是函数 manifest 的 `resources.forms` 绑定和函数调用授权，不是页面用户对目标表单的直接提交入口；报名、签到、福利选择等内部多表写入应走 App Function，不要为了写内部表单给普通用户开放原始 submit 权限。JS_CODE V2 仍兼容，但新逻辑建议写成 function，再由 `function_call` 节点、`sdk.function.invoke(code, { input })` 或 `/:appType/v1/functions/:code/invoke.json` 调用。直接运行时接口默认要求调用者具备应用自动化管理权限；普通页面调用必须在函数 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles` 或 `scope_policy`，`roleCodes` 只用于当前应用角色精确匹配，不支持 `"*"` / `"all-app-roles"`。自动化/流程内部调用走服务端受控上下文。内部业务表单需要关闭原始写入接口时，在表单 settings 中设置 `runtimeWrite.mode="function_only"`。
+后端业务逻辑优先声明为 App Function：源码放在 `src/functions/<functionCode>/index.ts`，资源 manifest 放在 `src/resources/functions/<functionCode>.json`。函数运行在 trusted_node 中，通过 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.files.readAsBase64`、`ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.organization`、`ctx.platform.roles`、`ctx.platform.api` 等受控 API 访问平台能力；自动化、流程和运行时接口都可以调用同一个 function。`ctx.files.readAsBase64` 只读取当前 `formData` 已授权的图片附件，或由当前应用的 `formCode/formUuid + formInstId + fieldId` 定位的图片；它不会下载任意 URL，单文件上限为 10 MiB，Base64 不应写入日志、函数返回值或业务表。已发布可信代码可以访问当前租户、当前应用内的资源，Function `resources` 是可选的环境映射、审计和影响分析信息，不再是逐函数权限白名单；跨应用、跨租户和外部敏感能力仍受平台边界限制。`ctx.process` 复用正式工作流服务，以真实运行时 operator 执行，流程实例、任务授权、操作日志、事件和 replay 语义与 PageSdk 后端接口一致。角色查询和角色成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`，底层 `ctx.platform.api` 返回 HTTP 包装和平台 envelope，需要业务代码自行解包。运行时页面调用会在 `ctx.operator`、`ctx.currentUser`、`ctx.permissions` 中注入可信的角色上下文；敏感业务动作必须读取这些服务端上下文，不要信任页面 input 里传入的角色字段。`ctx.form.createOne/updateOne/updateById` 是后端受控写入，不是页面用户对目标表单的直接提交入口；内部多表写入应走 App Function，不要为了函数写入给普通用户开放原始 submit 权限。内部业务表单需要关闭原始写入接口时，在表单 settings 中设置 `runtimeWrite.mode="function_only"`。
 
 App Function 访问第三方凭据时使用 `app_function_secrets_v1`：manifest 顶层只声明 `secretRefs: [{ "name": "dingtalk_org_app_key", "required": true }]`，同时使用 `definitionJson.version="function_v2"`、`runtimeContractVersion="trusted_node_v2"`；源码通过 `await ctx.secrets.get(name)` 解析，并通过 `ctx.utils.http` 访问受控公网 HTTPS（该桥接不会携带平台 Runtime token）。值只能经 `openxiangda secret create|rotate --value-stdin --change <id> --profile <name>` 或隐藏 TTY 输入，禁止进入 Git、manifest、源码、构建产物、plan、日志或异常。带 `secretRefs` 的 Function 必须走 `backend_release_v2`；需要整应用原子发布时先执行 `resource publish function --only <code> --stage-only`，再把返回的真实 `stagedResource` 交给 `release app-finalize --staged-resources-json ...` 完成 `atomic_staged_children_v2`。默认直接激活的 Backend Release 只返回 `activeResource`，不会伪装成 staged；旧平台 capability 不完整时 CLI 会失败关闭，绝不忽略绑定。
 

package/lib/cli.js

@@ -22178,16 +22178,28 @@ function formSettingValuesFromSnapshot(frozen) {
   };
 }
 
+function formSettingManifestSettings(item) {
+  const resourceCode = String(item.code || item.formCode || '').trim();
+  if (
+    item.settings === undefined &&
+    item.runtimeWrite === undefined &&
+    !resourceCode
+  ) {
+    return undefined;
+  }
+  return {
+    ...(item.settings || {}),
+    ...(item.runtimeWrite !== undefined
+      ? { runtimeWrite: item.runtimeWrite }
+      : {}),
+    ...(resourceCode ? { openxiangdaResourceCode: resourceCode } : {}),
+  };
+}
+
 function buildFormSettingBundleBody(item) {
   const body = {};
-  if (item.settings !== undefined || item.runtimeWrite !== undefined) {
-    body.settings = {
-      ...(item.settings || {}),
-      ...(item.runtimeWrite !== undefined
-        ? { runtimeWrite: item.runtimeWrite }
-        : {}),
-    };
-  }
+  const settings = formSettingManifestSettings(item);
+  if (settings !== undefined) body.settings = settings;
   for (const key of [
     'name',
     'schema',
@@ -25936,13 +25948,8 @@ function formSettingEquals(desired, existing = {}) {
       return false;
     }
   }
-  if (desired.settings !== undefined || desired.runtimeWrite !== undefined) {
-    const expectedSettings = {
-      ...(desired.settings || {}),
-      ...(desired.runtimeWrite !== undefined
-        ? { runtimeWrite: desired.runtimeWrite }
-        : {}),
-    };
+  const expectedSettings = formSettingManifestSettings(desired);
+  if (expectedSettings !== undefined) {
     const currentSettings = unwrapFormSettingPlanValue(
       existing.settings,
       'settings'

package/lib/source-dependencies.js

@@ -849,29 +849,22 @@ function validateManifestSourceBindings(options = {}) {
 
   for (const target of index.targets) {
     const label = `${target.targetKey.replace(/s$/, '')} ${target.code}`;
-    const transitiveMissing = [];
+    const undeclared = [];
     for (const reference of target.resourceReferenceDetails) {
       const declared = target.declaredResources[reference.bucket] || [];
       if (declared.includes(reference.code)) continue;
       if (reference.bucket === 'forms' && /^FORM[_-]/i.test(reference.code)) continue;
-      const message =
-        `${label}: ${reference.file}:${reference.line} ${reference.api} 引用 ${reference.bucket}.${reference.code}，` +
-        `但 manifest 未声明。请将 "${reference.code}" 加入 resources.${reference.bucket}`;
-      if (target.entryFiles.includes(reference.file)) {
-        errors.push(message);
-      } else {
-        transitiveMissing.push(reference);
-      }
+      undeclared.push(reference);
     }
-    if (transitiveMissing.length > 0) {
+    if (undeclared.length > 0) {
       const codes = Array.from(
-        new Set(transitiveMissing.map(reference => `${reference.bucket}.${reference.code}`))
+        new Set(undeclared.map(reference => `${reference.bucket}.${reference.code}`))
       ).sort();
       const visible = codes.slice(0, 12);
       warnings.push(
-        `${label}: 传递依赖中发现 manifest 未声明的资源引用: ${visible.join(', ')}` +
+        `${label}: 源码引用了未在逐资源清单声明的应用内资源: ${visible.join(', ')}` +
           `${codes.length > visible.length ? ` 等 ${codes.length} 项` : ''}。` +
-          '静态分析无法证明相关导出一定被当前入口调用；若会执行，请补充对应 resources 声明'
+          '平台运行时将按当前租户和应用自动解析；resources 仅用于显式映射、审计和影响分析'
       );
     }
     for (const warning of target.warnings) {

package/openxiangda-skills/SKILL.md

@@ -135,7 +135,7 @@ When the same change already has staged FormRelease children before a fresh base
 
 When a Function or Automation is selected because its TypeScript source changed, publishing is source-only by default. Backend Release v2 accepts source-backed create, source-free declarative Automation manifest create, source-only update, and manifest replacement update in one immutable child and one database transaction, so a stale member produces zero resource writes and noops do not advance versions/timestamps. A new Automation with a complete `definitionJson.version="v3"` and no `sourceFile` automatically uses manifest create without `--replace-manifest`; an incomplete definition still fails closed. `--stage-only` is fail-closed: every selected mutation must enter that child, and a missing/incompatible Backend Release API never falls back to direct writes. Online bindings, input/output contracts, metadata, trigger/view configuration, and enabled/published state remain unchanged unless exact `--replace-manifest --reason "..."` authority was provided for an existing resource.
 
-Treat resource bindings as a double manifest contract. Automation outer `resources` and runtime `definitionJson.resources` must be exactly equal. A Function may omit the runtime duplicate because the outer manifest is authoritative, but an explicit runtime declaration must match it. Source-only updates require the active online binding set to contain every expected Form/DataView binding; an intentional manifest replacement requires an exact set. Root App finalization reads the active Function/Automation binding back after activation and fails if it differs from the sealed contract.
+Treat resource declarations as environment mapping and release-observability metadata, not as per-Function authorization. Trusted code can access Forms/DataViews inside its current tenant and application without repeating every resource in every manifest; cross-app and cross-tenant access remains forbidden. Source analysis reports undeclared application resources as warnings. Explicit duplicate Automation outer/runtime declarations must still match, and explicit environment-specific code-to-ID mappings remain part of the sealed/read-back release contract.
 
 An App Function may declare metadata-only top-level `secretRefs: [{ name, required }]` only with `function_v2` + `trusted_node_v2`; source resolves values with `await ctx.secrets.get(name)` and uses `ctx.utils.http` for controlled public HTTPS. Create/rotate values through hidden TTY or `openxiangda secret ... --value-stdin --change <change> --profile <name>`. Never put values in arguments, files, manifests, state, plans, logs, errors, or chat. Secret bindings require `backend_release_v2` and whole-app `atomic_staged_children_v2`; a missing capability is fail-closed and never uses the legacy source PATCH. For whole-app activation use exact-scope `resource publish <type> --only <code> --stage-only`, then pass the returned verified `stagedResource` to `release app-finalize`; an active Backend Release is never labeled staged.
 

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

@@ -291,7 +291,7 @@ Author source in `src/js-code-nodes/<scriptCode>/index.ts`. AI-authored source m
 
 The backend runs the snapshot in the trusted Node runtime, applies the node timeout (`30000` ms by default), stores execution logs, and writes the returned value to the node output and `variables.node_<nodeId>`. Scripts may use `export default async function (ctx) {}`, `module.exports = async (ctx) => {}`, `require`, `process`, `Buffer`, arbitrary HTTP, and `platform.api` for `/openxiangda-api/v1`.
 
-Runtime context includes `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`. Prefer the higher-level resource helpers when available: `ctx.resources.resolveForm/resolveDataView/resolveConnector`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.dataView.query/stats`, `ctx.connector.call/invoke`, `ctx.notification.*`, `ctx.platform.roles.*`, and `ctx.platform.api.*`. Use `ctx.platform.roles.findByCode/addUsers/removeUser` for app role member synchronization; raw `ctx.platform.api.*` returns an HTTP response and platform envelope. App Function and trusted-node form writes are backend operations over declared resources, not direct page-user submit access; keep internal forms closed to raw user submission unless the business requires it. Legacy data/process bridge methods remain available as `ctx.methods.queryOneData`, `queryManyData`, `getDataByFormInstanceId`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
+Runtime context includes `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`. Prefer the higher-level resource helpers when available: `ctx.resources.resolveForm/resolveDataView/resolveConnector`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.files.readAsBase64`, `ctx.dataView.query/stats`, `ctx.connector.call/invoke`, `ctx.notification.*`, `ctx.platform.roles.*`, and `ctx.platform.api.*`. `ctx.files.readAsBase64` reads only server-authorized image attachments from current form data or an explicit form record/field reference, never an arbitrary URL; the file limit is 10 MiB and its Base64 result must not be logged or persisted. Use `ctx.platform.roles.findByCode/addUsers/removeUser` for app role member synchronization; raw `ctx.platform.api.*` returns an HTTP response and platform envelope. Published App Function and trusted-node code may write forms in its current tenant/application; per-resource declarations are mapping and audit metadata, not an application-internal allowlist. This does not grant page users direct submit access, so keep internal forms closed to raw user submission unless the business requires it. Legacy data/process bridge methods remain available as `ctx.methods.queryOneData`, `queryManyData`, `getDataByFormInstanceId`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
 
 Code automation also exposes `ctx.logger.debug/info/warn/error(message, data?)`. AI-authored code should log input parsing, query conditions, external calls, writes, branch decisions, and caught errors. Logs are stored as full raw execution data by default. Use CLI diagnosis commands:
 

package/openxiangda-skills/references/connector-resources.md

@@ -32,7 +32,7 @@ Notification manifests live under `src/resources/notifications/` and contain `te
 
 Data view manifests live under `src/resources/data-views/` and define read-only joined or aggregate query resources. Use `storageMode: "materialized"` for refreshed lists/reports where lag is acceptable, and `storageMode: "live"` for bounded real-time query shapes. Use row views with `sdk.dataView.query` and aggregate views with `sdk.dataView.stats`. Before generating one, confirm freshness tolerance, query bounds, and indexes for materialized filters/sort fields/dimensions/date buckets. Do not use them for single-form CRUD, simple linkedForm selects, writes, write-back, or ad-hoc BI. See `data-views.md` before generating one.
 
-App Function manifests live under `src/resources/functions/`, with source in `src/functions/<functionCode>/index.ts`. Use them for reusable server-side logic that pages, automations, and workflows can share through `sdk.function.invoke` or `function_call` nodes. App Functions expose controlled runtime helpers such as `ctx.resources`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, `ctx.platform.roles`, and `ctx.platform.api`; they do not expose raw SQL or Redis in the current MVP. `ctx.process` uses the official workflow services with the real operator and is restricted to the current app plus Function `resources.forms` bindings. Use `ctx.platform.roles.list/findByCode/addUsers/removeUser` for app role lookup and membership changes; raw `ctx.platform.api` returns an HTTP response plus platform envelope. Runtime page invocations also expose trusted role context on `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, and `ctx.permissions`; use that context for server-side authorization, and never trust page-submitted role codes for sensitive actions. Page-call grants should use `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`); `roleCodes` is only for current app-role grants and does not support `"*"` or `"all-app-roles"`. App Function form writes are trusted backend writes governed by declared `resources.forms` and function invocation authorization, not by direct page-user submit access to the target form. For internal function-only forms, publish form settings with `runtimeWrite.mode="function_only"` so raw write endpoints are closed. App Function organization writes require `app:organization:manage` on the real operator/audit actor. Use JS_CODE V2 only for node-local workflow/automation scripts.
+App Function manifests live under `src/resources/functions/`, with source in `src/functions/<functionCode>/index.ts`. Use them for reusable server-side logic that pages, automations, and workflows can share through `sdk.function.invoke` or `function_call` nodes. App Functions expose controlled runtime helpers such as `ctx.resources`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, `ctx.platform.roles`, and `ctx.platform.api`; they do not expose raw SQL or Redis in the current MVP. Published trusted code may use all application-owned Forms/DataViews in the current tenant/app. Function `resources` remains optional code-to-ID mapping and audit metadata, while cross-app/cross-tenant access stays forbidden. Use `ctx.platform.roles.list/findByCode/addUsers/removeUser` for app role lookup and membership changes; raw `ctx.platform.api` returns an HTTP response plus platform envelope. Runtime page invocations also expose trusted role context on `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, and `ctx.permissions`; use that context for business authorization, and never trust page-submitted role codes for sensitive actions. Page-call grants should use `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`); `roleCodes` is only for current app-role grants and does not support `"*"` or `"all-app-roles"`. App Function form writes are trusted backend operations, not direct page-user submit access to the target form. For internal function-only forms, publish form settings with `runtimeWrite.mode="function_only"` so raw write endpoints are closed. App Function organization writes require `app:organization:manage` on the real operator/audit actor. Use JS_CODE V2 only for node-local workflow/automation scripts.
 
 Auth manifests live under `src/resources/auth/`. Use them to enable app-level login methods and bind phone-code/CAS/custom providers to App Functions. Auth provider functions are called only by the platform auth flow. They validate external credentials and return identity assertions such as `phone`, `email`, `externalId`, or `unionId`; they must not issue tokens, set cookies, or mutate platform user/binding tables.
 

package/openxiangda-skills/references/pages/page-sdk.md

@@ -16,6 +16,7 @@ Guidelines:
 - Use `sdk.function.invoke(code, { input })` for reusable backend business logic declared under `src/resources/functions/` and `src/functions/`. Do not implement multi-form orchestration, connector fan-out, notification orchestration, or permission-sensitive backend rules directly in a page component.
 - Use `sdk.connector.invoke`, `sdk.connector.call("connector.api")`, or `sdk.connector.download` for external services. The SDK calls the platform runtime connector endpoint; it must not call third-party domains directly.
 - Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
+- Use `sdk.export.create` and `sdk.export.get` for asynchronous XLSX exports. Simple pages may send a declarative workbook definition. Complex or reusable exports should send only a published App Function `definitionCode`, the current query snapshot, export scope, and stable selected row IDs. The server executes `structured_export_provider_v1` with fresh user permissions; never upload executable rendering code from the browser. See `docs/structured-export-v1.md`.
 - Use `AttachmentPreviewList`, `ImagePreviewGrid`, or `useFilePreview` from `openxiangda/runtime/react` for in-page attachment previews in a custom React SPA page. They use the current PageSdk context and enforce the platform capability and ticket contracts. Use `sdk.createFileAccessTicket(bucketName, objectName, fileName, "preview", { appType })` only when the page needs a shareable or new-window preview link. `appType` defaults to the current page context. Open `response.result.previewPageUrl`; do not use `previewUrl` or `/service/file/preview-by-ticket/:ticket` as the page entry.
 - Use `sdk.organization.departments.*` and `sdk.organization.accounts.*` only for intentional organization pages. Read-only list/detail pages need `app:organization:read` or `app:organization:manage`; writes and password operations need `app:organization:manage`. Do not call legacy `/user` or `/department` endpoints from pages.
 - Use `sdk.workCenter.listItems({ boxType })` and `sdk.workCenter.getStats()` for current-user work center lists and counts. `boxType` is one of `todo`, `done`, `cc`, or `initiated`. This is the end-user task/handled/cc/initiated surface; do not build todo pages by reading workflow operation logs, automation logs, or raw process-task tables.
@@ -187,7 +188,32 @@ App Function source should prefer `export default async function(ctx, input) {}`
 The second argument is the `input` passed by `sdk.function.invoke`, and the
 same value is also available as `ctx.input` for compatibility.
 
-Use App Functions when the logic must run server-side and be reusable by pages, automations, or workflows. Runtime invocation requires app automation management permission by default. To let ordinary app users call a function from a page, declare `definitionJson.runtimeInvoke.audience` with `authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`; use `roleCodes` only for current app-role grants. Do not use `"*"` or `"all-app-roles"` as role codes. Inside the function, authorize sensitive actions with trusted runtime context such as `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, or `ctx.permissions`; do not trust role codes sent in the page input. When the function writes forms with `ctx.form.createOne/updateOne/updateById`, treat the write as a trusted backend operation over declared `resources.forms`; do not open direct submit permission on internal forms just for that page action.
+Use App Functions when the logic must run server-side and be reusable by pages, automations, or workflows. Runtime invocation requires app automation management permission by default. To let ordinary app users call a function from a page, declare `definitionJson.runtimeInvoke.audience` with `authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`; use `roleCodes` only for current app-role grants. Do not use `"*"` or `"all-app-roles"` as role codes. Inside the function, authorize sensitive actions with trusted runtime context such as `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, or `ctx.permissions`; do not trust role codes sent in the page input. Published trusted code may write any form in its current tenant/application; per-function `resources.forms` is optional mapping and audit metadata, not an authorization allowlist. Do not open direct submit permission on internal forms just for that page action.
+
+Server-defined export:
+
+```ts
+const response = await sdk.export.create({
+  exportKey: "orders",
+  definitionCode: "order_export_provider",
+  definitionInput: { variant: "finance" },
+  query: {
+    filters,
+    sorts: [{ field: "createTime", direction: "descend" }],
+  },
+  scope: selectedIds.length ? "selected" : "all",
+  rowIds: selectedIds,
+})
+
+const task = response.result
+const latest = task ? await sdk.export.get(task.id) : null
+```
+
+`definitionCode` must identify a published, permission-scoped App Function
+implementing `structured_export_provider_v1`. Its `describe` phase owns the
+workbook and column definition; its paged `query` phase owns trusted data
+selection and custom computed fields. The platform owns the queue, permission
+revalidation, XLSX generation, formula hardening, storage, and download ticket.
 
 Organization management:
 

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

@@ -678,7 +678,7 @@ const result = await sdk.function.invoke("reservation_reminder_summary", {
 }
 ```
 
-适用边界：可复用后端业务逻辑、跨页面/自动化/流程共享的查询编排、连接器调用、通知编排、受控平台 API 调用。App Function 支持 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.roles`、`ctx.platform.api` 等受控 helper，当前 MVP 不暴露原始 SQL/Redis。应用角色查询和成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`；底层 `ctx.platform.api` 返回 HTTP 包装与平台 envelope，需要自行解包。`ctx.form.createOne/updateOne/updateById` 是后端受控写入，权限边界是 function manifest 的 `resources.forms` 和函数调用授权，不是页面用户对目标表单的直接提交权限；内部业务表单不要为了函数写入而开放普通用户原始 submit。运行时接口默认需要应用自动化管理权限；普通用户页面要调用时，用 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles` 或 `scope_policy`，不要把 `"*"`、`"all-app-roles"` 写进 `roleCodes`。自动化/流程内部调用走服务端上下文，不受页面运行时授权限制。若表单只能由函数/流程写入，在 `src/resources/settings/forms/<formCode>.json` 设置 `runtimeWrite.mode="function_only"` 关闭原始写入接口。
+适用边界：可复用后端业务逻辑、跨页面/自动化/流程共享的查询编排、连接器调用、通知编排、受控平台 API 调用。App Function 支持 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.roles`、`ctx.platform.api` 等受控 helper，当前 MVP 不暴露原始 SQL/Redis。应用角色查询和成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`；底层 `ctx.platform.api` 返回 HTTP 包装与平台 envelope，需要自行解包。已发布可信代码可以访问当前租户、当前应用内的资源；function manifest 的 `resources` 是可选映射、审计和影响分析信息，不再是逐函数权限白名单。页面用户仍不能直接提交内部表单，跨应用和跨租户访问仍被拒绝。运行时接口默认需要应用自动化管理权限；普通用户页面要调用时，用 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles` 或 `scope_policy`，不要把 `"*"`、`"all-app-roles"` 写进 `roleCodes`。若表单只能由函数/流程写入，在 `src/resources/settings/forms/<formCode>.json` 设置 `runtimeWrite.mode="function_only"` 关闭原始写入接口。
 
 ## 5. Workflow — `src/resources/workflows/<code>/workflow.json`（manifest）+ `src/workflows/<code>/workflow.ts`（代码优先）
 

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

@@ -389,7 +389,7 @@ For reusable backend logic that should be shared by pages, automations, and work
 
 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`; these calls are restricted to the current app and declared `resources.forms`, and reuse the real operator's official workflow permission, operation-log, event, idempotency, and replay paths. 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 over declared resources, 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`.
+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`:
 

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

@@ -63,11 +63,11 @@ openxiangda resource publish function --only function_a,function_b --profile <na
 
 Selectors apply before manifest parsing, source dependency analysis, and JS_CODE typecheck/build. A scoped Function/Automation plan must touch only the selected targets plus their transitive/shared/ambient dependencies; an unscoped plan intentionally retains full-workspace behavior. Resource commands use the canonical scoped builder packaged with the installed CLI for standard workspaces, so old checked-in builders still receive the optimization; refresh/bootstrap the workspace script only for equivalent manual `pnpm build-js-code` behavior. Nonstandard custom builders remain an explicit compatibility fallback.
 
-Function/Automation source analysis also extracts statically declared Form filter and order fields. `resource plan` compares them with each bound Form's frozen online schema and reports `formFieldContracts`; publish fails before lease/write when a binding or field is missing. Fix the source or stage the Form schema in the same reviewed release instead of waiting for a production SQL-column error. Dynamic field names remain runtime-validated by the platform and return `FORM_FIELD_NOT_FOUND` as a configuration error.
+Function/Automation source analysis also extracts statically declared Form filter and order fields. `resource plan` resolves them through the target application's resource registry, compares them with each Form's frozen online schema, and reports `formFieldContracts`; publish fails before lease/write when the application mapping or field is missing. A source reference does not need to be repeated in every Function/Automation manifest. Fix the application mapping/source or stage the Form schema in the same reviewed release instead of waiting for a production SQL-column error. Dynamic field names remain runtime-validated by the platform and return `FORM_FIELD_NOT_FOUND` as a configuration error.
 
 Source-triggered Function/Automation targets use Backend Release v2 when the platform exposes that capability. One child may mix source-backed create, source-free declarative Automation manifest create, source-only update, and manifest replacement update through explicit per-resource `operation/mode`; the CLI freezes the current Backend Release parent plus Git/change baseline, then runs `prepare -> verify -> activate` or stops verified for `--stage-only`. A new Automation with a complete `definitionJson.version="v3"` and no `sourceFile` automatically uses manifest create without `--replace-manifest`; an incomplete definition still fails closed. Activation CAS-checks the entire set and applies all updates in one transaction. `--stage-only` and Secret-bound Function publishing fail closed when Backend Release v2 is unavailable; compatibility fallback is limited to non-staged, non-Secret publishing after an explicit Backend head 404. Existing online bindings, contracts, metadata, trigger/view configuration, and enabled/published state remain unchanged; noops do not advance versions/timestamps. A deliberate whole-definition replacement of an existing resource requires exact `--only/--code` and `--replace-manifest --reason "<why>"`; SDD bypass does not imply replacement authority.
 
-Resource bindings are a double manifest contract. Automation outer `resources` and runtime `definitionJson.resources` must match exactly. Function runtime resources may be omitted because the outer manifest is authoritative, but explicit duplicates must match. Source-only requires the active online binding set to contain every expected Form/DataView binding; manifest replacement requires exact equality. After Root App activation, read back active Function/Automation bindings and fail the release if they differ from the sealed contract.
+Resource declarations are mapping, audit, and impact-analysis metadata rather than per-Function authorization. Trusted application code may use any Form/DataView in its current tenant and app; the platform still rejects cross-app/cross-tenant access. Statically discovered source references that are absent from a Function/Automation manifest are warnings, not publish blockers. When an outer Automation `resources` declaration and runtime `definitionJson.resources` are both explicitly present they must still match, and explicit resource bindings remain sealed/read back so environment-specific code-to-ID mappings cannot silently drift.
 
 Repository identity remains strict across immutable releases. If a clone-derived primary repository ID differs from the frozen change source base, the CLI may canonicalize Backend, Workflow, and Root App Release payloads to the frozen ID only when that ID is already present in `releaseSourceRevision.repoAliases`; no alias intersection fails with `RELEASE_SOURCE_REPOSITORY_MISMATCH` before prepare.
 

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

@@ -103,7 +103,7 @@ Use `workflow pull` to inspect the live definition. Use `workflow list --json` a
 
 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 can call `ctx.process.startFromExistingInstance`, `resolveCapabilities`, `resubmitTask`, `withdraw`, and `transferTask`; the bridge uses the current app, declared `resources.forms`, and the real operator's workflow/task authorization, audit, event, and replay contracts. `ctx.form.createOne/updateOne/updateById` are trusted backend writes governed by declared `resources.forms` and function invocation authorization; keep internal forms closed to direct user submit unless the business explicitly needs raw form submission. For internal function-only forms, set form settings `runtimeWrite.mode="function_only"` instead of relying only on missing submit permission groups.
+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`.
 
@@ -143,7 +143,7 @@ Inside the TypeScript script, prefer `export default async function (ctx) {}` or
 - 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.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask` for App Functions, `ctx.dataView.query/stats`, and `ctx.connector.call/invoke`.
+- 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:

package/package.json

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

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

@@ -35926,6 +35926,35 @@ var createPageSdk = (context) => {
       });
     }
   };
+  const structuredExport = {
+    create: (params) => request({
+      path: buildOpenXiangdaAppPath(
+        context,
+        params.appType,
+        "/exports"
+      ),
+      method: "post",
+      body: {
+        ...params,
+        appType: void 0,
+        protocol: "structured_export_v1"
+      }
+    }),
+    get: (taskId, params = {}) => {
+      const normalizedTaskId = String(taskId || "").trim();
+      if (!normalizedTaskId) {
+        throw new Error("\u5BFC\u51FA\u4EFB\u52A1 ID \u4E0D\u80FD\u4E3A\u7A7A");
+      }
+      return request({
+        path: buildOpenXiangdaAppPath(
+          context,
+          params.appType,
+          `/exports/${encodePathSegment(normalizedTaskId)}`
+        ),
+        method: "get"
+      });
+    }
+  };
   const notification2 = {
     sendByType: (params) => request({
       path: buildOpenXiangdaAppPath(
@@ -36100,6 +36129,7 @@ var createPageSdk = (context) => {
     request,
     download,
     createFileAccessTicket,
+    export: structuredExport,
     transport: {
       request,
       download
@@ -44846,14 +44876,27 @@ function AdminList(props) {
     if (!dataSource.createExportTask) return;
     setExporting(true);
     try {
+      const exportColumns = (preference.columns || []).filter((column) => column.visible !== false).map((column) => columns.find((item) => item.key === column.key)).filter(
+        (definition) => Boolean(
+          definition && definition.exportable !== false && definition.export !== false
+        )
+      ).map((definition) => {
+        const configured = definition.export || {};
+        const title = typeof definition.title === "string" || typeof definition.title === "number" ? String(definition.title) : definition.key;
+        const dataPath = Array.isArray(definition.dataIndex) ? definition.dataIndex.join(".") : definition.dataIndex || definition.key;
+        return {
+          key: definition.key,
+          title,
+          valuePath: dataPath,
+          ...configured
+        };
+      });
       const input = {
         scope,
         query: { ...query },
         rowIds: scope === "selected" ? selectedKeys : void 0,
-        fieldKeys: (preference.columns || []).filter((column) => column.visible !== false).map((column) => column.key).filter((key) => {
-          const definition = columns.find((column) => column.key === key);
-          return definition && definition.exportable !== false;
-        }),
+        fieldKeys: exportColumns.map((column) => column.key),
+        columns: exportColumns,
         fileName
       };
       const created = await dataSource.createExportTask(input);
@@ -45751,13 +45794,33 @@ var createExportClient = (options, source) => {
   )}/admin-list/exports`;
   return {
     createExportTask: async (input) => {
+      const normalizedInput = {
+        ...input,
+        rowIds: input.rowIds?.map(
+          (rowId) => typeof rowId === "number" ? rowId : String(rowId)
+        )
+      };
+      if (options.sdk.export?.create) {
+        const response2 = await options.sdk.export.create({
+          appType,
+          exportKey: options.listKey,
+          source,
+          ...normalizedInput,
+          definitionCode: options.exportDefinitionCode,
+          definitionInput: options.exportDefinitionInput
+        });
+        if (!response2.result) {
+          throw new Error("\u521B\u5EFA\u5BFC\u51FA\u4EFB\u52A1\u5931\u8D25\uFF1A\u670D\u52A1\u7AEF\u672A\u8FD4\u56DE\u4EFB\u52A1");
+        }
+        return response2.result;
+      }
       const response = await options.sdk.request({
         path: basePath,
         method: "post",
         body: {
           listKey: options.listKey,
           source,
-          ...input
+          ...normalizedInput
         }
       });
       if (!response.result) {
@@ -45766,6 +45829,13 @@ var createExportClient = (options, source) => {
       return response.result;
     },
     getExportTask: async (taskId) => {
+      if (options.sdk.export?.get) {
+        const response2 = await options.sdk.export.get(taskId, { appType });
+        if (!response2.result) {
+          throw new Error("\u67E5\u8BE2\u5BFC\u51FA\u4EFB\u52A1\u5931\u8D25\uFF1A\u4EFB\u52A1\u4E0D\u5B58\u5728");
+        }
+        return response2.result;
+      }
       const response = await options.sdk.request({
         path: `${basePath}/${encodeURIComponent(taskId)}`,
         method: "get"