openxiangda 1.0.159 → 1.0.161

package/openxiangda-skills/SKILL.md

@@ -1,253 +1,128 @@
 ---
 name: openxiangda
-description: "Use OpenXiangda for any private low-code platform or sy-lowcode-app-workspace work: architecture design, app creation, forms, pages, resources, workflows, automations, JS_CODE, permissions, organization/account management, data views, connectors, notifications, publishing, deployment, diagnosis, feedback, profile/login state, and CLI commands. Trigger on OpenXiangda, 享搭, 私有化低代码, 低代码平台, .openxiangda/state.json, app-workspace.config.ts, or openxiangda CLI usage."
+description: "Use OpenXiangda for private low-code platform work: app workspaces, forms, pages, resources, functions, automations, workflows, permissions, publishing, deployment, diagnosis, profiles, and the openxiangda CLI."
 ---
 
 # OpenXiangda
 
-OpenXiangda is a lightweight bridge between an AI coding tool and a private low-code platform. Normal app development uses a platform domain, a normal-user login, and `/openxiangda-api/v1`; it does not use AK/SK. External backend and third-party integrations are a separate track that uses the `openxiangda-open-api` skill and `/dingtalk-api/v1.0`.
-
-OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` publishes form/page bundles with `openxiangda workspace publish`. Phase 6 `react-spa` workspaces are standard React/Vite apps: publish resources with `openxiangda resource publish`, then publish the frontend dist with `openxiangda runtime deploy`. Do not send React SPA routes through old `isRenderNav`, app-shell, or workbench page parameters.
-
-## TL;DR — Decision Card
-
-**If the workspace has `.openxiangda/state.json` or `app-workspace.config.ts`, you are in an OpenXiangda app workspace. Read this card before any tool call.**
-
-### Routing — user intent → skill / command
-
-| User says (zh / en)                                      | Skill                                                                                      | First command                                                                                                                                            |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 发布 classic workspace / 上线旧模式                      | `openxiangda-core`                                                                         | `openxiangda workspace publish --profile <name> --changed --dry-run`                                                                                     |
-| 发布 React SPA / Phase 6 runtime                         | `openxiangda-core`                                                                         | `openxiangda resource publish --profile <name>` then `openxiangda runtime deploy --profile <name>`                                                       |
-| 只发布改动 / 增量 / 单页 / 单表                          | `openxiangda-core`                                                                         | `... --changed` / `--page <code>` / `--form <code>` / `--only pages/a,forms/b`                                                                           |
-| 架构设计 / 详细设计 / 新应用需求 / 需求文档转享搭应用    | `openxiangda-architecture-design`                                                          | read `references/architecture-design.md`; inspect workspace/app state before coding                                                                      |
-| 创建应用 / 新建 app / scaffold / 初始化工作区            | `openxiangda-app`                                                                          | `openxiangda workspace init <dir> --profile <name> --app-name "..."`                                                                                     |
-| 绑定已有应用 / bind existing app                         | `openxiangda-app`                                                                          | `openxiangda workspace bind --profile <name> --app-type APP_XXX`                                                                                         |
-| 创建 / 修改表单字段 / 表单页 / schema                    | `openxiangda-form`                                                                         | edit `src/forms/<code>/{schema.ts,page.tsx}` → `workspace publish --form <code>`                                                                         |
-| 导出表单数据 / 图片 / 附件 / Excel / zip                 | `openxiangda-form`                                                                         | `openxiangda form export <formCode> --mode xlsx|xlsx-images|package --profile <name>`                                                                    |
-| 创建 / 修改自定义代码页 / portal / dashboard             | `openxiangda-page`                                                                         | edit `src/pages/<code>/` → `workspace publish --page <code>`                                                                                             |
-| 审批流程 / workflow / 流程节点 / JS_CODE                 | `openxiangda-workflow-automation`                                                          | `openxiangda workflow validate / create / publish`                                                                                                       |
-| 自动化 / 定时任务 / 提交触发 / cron                      | `openxiangda-workflow-automation`                                                          | `openxiangda automation validate / create / publish / enable`                                                                                            |
-| App Function / function_call / 可复用后端逻辑            | `openxiangda-workflow-automation`                                                          | declare `src/resources/functions/<code>.json` + `src/functions/<code>/index.ts`                                                                          |
-| 应用登录 / Auth SDK / 手机号验证码 / CAS / 钉钉免登      | `openxiangda-architecture-design` + `openxiangda-page`                                     | design security gate first, then declare `src/resources/auth/<code>.json` and use `createAuthClient` / `LoginPage`                                       |
-| 账号权限 / 角色 / 权限组 / 字段权限 / 数据范围 / RBAC   | `openxiangda-permission-settings`                                                          | `openxiangda design gates --topic permissions --json` → choose permission mode → `openxiangda permission ...` / `openxiangda settings ...`              |
-| 平台部门 / 平台账号 / 重置密码 / 组织账号管理            | `openxiangda-architecture-design` + `openxiangda-page`                                     | check `openxiangda organization capabilities --json`; use `sdk.organization` / `ctx.organization` only after `app:organization:manage` is granted         |
-| 外部人员无需登录访问 / 公开报名 / 公开查询 / public page | `openxiangda-architecture-design` + `openxiangda-permission-settings` + `openxiangda-page` | 先确认公开范围、外部角色、ticket、grants；再声明 `routes` + `public-access`，并用 `OpenXiangdaProvider` + `OpenXiangdaPageProvider` + `PublicAccessGate` |
-| 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错            | `openxiangda-inspect`                                                                      | `openxiangda app snapshot <APP_XXX> --profile <name> --json`                                                                                             |
-| 登录 / 切换平台 / profile / token / whoami               | `openxiangda-core`                                                                         | `openxiangda env --profile <name>` / `openxiangda auth status`                                                                                           |
-| 多表只读联表 / 固定口径统计 / 强实时复杂查询 / 看板指标  | `openxiangda-form` (data view)                                                             | declare `src/resources/data-views/<code>.json` with `storageMode` → `resource publish`                                                                   |
-| 调外部 / 第三方 API / 钉钉 / 自建系统                    | `openxiangda-page` (connector)                                                             | declare `src/resources/connectors/<code>.json` → `sdk.connector.invoke`                                                                                  |
-| 外部后端 / 三方系统调用享搭 / AK/SK / 开放接口          | `openxiangda-open-api`                                                                     | `openxiangda open-api spec list --search <keyword> --json` → describe the selected operation                                                             |
-
-### Hard rules — always
-
-- ✅ Publish classic workspaces through `openxiangda workspace publish --profile <name>`; publish React SPA forms first with `openxiangda workspace publish --form <formCode>`, then resources/runtime through `openxiangda resource validate` → `openxiangda resource publish --dry-run` → `openxiangda resource publish` → `openxiangda runtime deploy`.
-- ✅ High-risk changes must be attached to OpenXiangda SDD v2 records before implementation/publish. Run `openxiangda sdd context --json`; for forms/pages/resources/functions/automations/workflows/JS_CODE/runtime/config changes create or continue `openxiangda sdd propose <change>`, wait for user confirmation, run `openxiangda sdd approve <change>`, then complete `coverage.json`, `release.json`, `evidence.md`, and `tasks.md` before `openxiangda sdd verify <change> --changed`.
-- ✅ Before publishing AI-authored changes, run `openxiangda workspace plan --changed --json` and `openxiangda workspace check --changed`. Fix reported fake IDs, fallback data, direct `/openxiangda-api` page calls, missing schema, or resource/runtime omissions before publish.
-- ✅ When unsure about runtime response shape, run `openxiangda contract explain <contract-name> --json`. `sdk.form.create` returns identifiers and generated serial number values only; fetch detail explicitly for full row data, formula results, or other server-generated fields.
-- ✅ Architecture-class requests are plan-gated by default. For 新应用、复杂页面、登录注册、公开访问、权限数据范围、流程自动化、连接器/通知、外部集成, first run `openxiangda doctor --json` when a workspace exists and `openxiangda design gates --topic <code> --json`; then ask the user to confirm the design. Before confirmation, only read files, inspect/snapshot, dry-run, ask questions, and write/output design docs. Do not edit source files, write platform resources, send notifications, publish, or deploy.
-- ✅ `runtime deploy` defaults to staged multipart `dist/` uploads plus a final manifest. Use `--upload-mode legacy-json` only for old platform servers.
-- ✅ User token lives in `~/.openxiangda/profiles.json`; project state in `.openxiangda/state.json` (IDs only).
-- ✅ Each profile (dev / prod / ...) has its own `appType` and resource IDs; never copy a `formUuid` / `pageId` / `workflowId` / `automationId` across profiles.
-- ✅ Run `openxiangda update check --json` at the start of substantial work; if `updateAvailable`, run `openxiangda update install` and `openxiangda skill install --force`.
-- ✅ For non-trivial app requirements, run the architecture design gate first: forms, fields, pages, permissions, data views, status/workflow, automation, notifications, and development tasks must be decided before coding.
-- ✅ For app login/auth requirements, run the auth security gate before coding: enabled methods, registration policy, identity matching keys, provider boundary, default roles, rate limits, audit fields, and third-party ownership must be confirmed.
-- ✅ For public/no-login access requirements, run the public access design gate before coding: public routes, external role codes, guest vs ticket, form/dataView/function/connector/storage grants, backend permission groups, and visible loading/error fallback states must be confirmed. New React SPA apps use `/view/:appType/public/*`, `src/resources/routes/`, `src/resources/public-access/`, and `PublicAccessGate`; route children that use Page SDK hooks must be inside `OpenXiangdaProvider` + `OpenXiangdaPageProvider`.
-- ✅ For account/role/permission/data-scope/query-param authorization requirements, run `openxiangda design gates --topic permissions --json` before coding. Pick one mode from `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`, write the permission matrix, and use roles/page-groups/form-groups/App Functions for real enforcement.
-- ✅ Public/no-login validation must inspect the JSON envelope, not only HTTP status. HTTP 200 with `code: "PUBLIC_GRANT_DENIED"` is a denied request; success requires `code` `200`, `"200"`, or compatible `0`, and no `success: false`.
-- ✅ Use first-class resource CLI commands for discovery, diagnosis, and small live fixes: `route`, `public-access`, `auth-config`, `function`, `connector`, `notification`, `organization`, `data-view`, `menu`, and `permission`. For multi-resource formal development, still prefer `src/resources/**` + `openxiangda resource validate|plan|publish`. If a direct CLI write is intentionally used, add `--write-manifest` when the repository should stay the source of truth.
-- ✅ For form-entry UX, pick components in this order: OpenXiangda platform form components → `antd` / `antd-mobile` wrappers → custom component only when neither exists.
-- ✅ In React SPA apps, keep imports on public package entrypoints such as `openxiangda`, `openxiangda/runtime`, and `openxiangda/runtime/react`. The default template already groups large vendor chunks; if a bundle is too large, use route-level lazy loading and Vite `manualChunks`, not `openxiangda/packages/sdk/dist/...` internal paths.
-- ✅ For image thumbnails or lightweight previews, use `imageCompression` on `ImageField` or `AttachmentField`. Keep the original `url` for the source file and use `thumbUrl` / `previewUrl` / `variants` for smaller images.
-- ✅ In form context, let `ImageField` and `AttachmentField` own preview UX. In standalone React SPA pages, use `AttachmentPreviewList`, `ImagePreviewGrid`, or `useFilePreview` from `openxiangda/runtime/react`; do not create a fake form context or import internal `FilePreviewContent` / `useFilePreviewController`. All paths must honor platform capability checks, and apps must not maintain local previewable-extension allowlists.
-- ✅ When a custom editable React SPA surface genuinely needs `FormProvider`, set `config.api` from `usePageFormRuntimeApi()`; use `createPageFormRuntimeApi(sdk)` outside hooks. Never implement the bridge as `api.request: config => sdk.request(...)`, because JSON transport drops `responseType: "blob"` and breaks binary attachment previews.
-- ✅ For data delivery with files, use `openxiangda form export <formCode> --mode xlsx|xlsx-images|package --profile <name>`. `package` writes a zip with `data.xlsx`, `attachments/`, and `manifest.json`; do not hand-write export URLs or stream binary content to stdout.
-- ✅ List pages, linked options, remote selectors, and report drill-downs must use paginated server-side queries with explicit searchable fields. Do not fetch a large page and filter in local state.
-- ✅ Treat workflow forms as an exception. Ordinary ticket/order/task/asset lifecycles use status fields, state machines, action logs, permissions, and automations; workflows are for real approval tasks.
-- ✅ Proactively submit platform feedback when you discover a defect, missing capability, unclear rule, repeated workaround, user-visible UX gap, or implementation uncertainty worth improving.
-
-### Hard rules — never
-
-- ❌ `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*` directly — they are workspace internals and miss the profile token injection. Use `openxiangda workspace publish ...` instead.
-- ❌ Asking the user to paste `AK` / `SK` / `appKey` / `appSecret` into chat. Normal OpenXiangda flows use the user token; authorized external backend work uses `open-api credential` for a direct secure handoff.
-- ❌ Searching the platform for a similar app name when `.openxiangda/state.json` has no binding — create a new app with `workspace init --app-name`.
-- ❌ Using `openxiangda form create` / `form publish` / `page publish` as the normal page generation path. They are low-level repair commands.
-- ❌ Implementing an architecture-class request before the user confirms the design. This includes creating files, mutating platform resources, publishing runtime, sending notifications, or calling live write/delete endpoints.
-- ❌ Running a full publish after editing one file. Default to `--changed --dry-run` → `--changed`, or targeted `--page` / `--form`.
-- ❌ Generating fake form instance IDs, mock rows, fallback schemas, or fallback display data to make a broken API path look successful.
-- ❌ Treating query parameters, frontend button hiding, hardcoded roles, mock role context, or `PermissionBoundary` alone as sensitive authorization. Query parameters may provide context or ticket input only; sensitive data still needs public-access grants, platform roles, form permission groups, or App Function checks.
-- ❌ Storing tokens, AK, SK, or third-party API secrets in project files. Shared env (`APP_OSS_*`, feedback robot) goes to `~/.openxiangda/.env`.
-- ❌ Raw native HTML form controls in AI-authored workspace code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, hand-written upload controls). They are allowed only inside OpenXiangda SDK/platform component internals.
-- ❌ Using `?publicAccess=guest` or form `publicAccess` settings for new React SPA apps. Those are legacy `sy-lowcode-view` compatibility only.
-- ❌ Importing OpenXiangda SDK internals such as `openxiangda/packages/sdk/dist/components/index.mjs` from business apps. Public entrypoints are the compatibility boundary; SDK build optimization belongs in OpenXiangda, not app-local deep imports.
-
-## Platform Routing
-
-Private platform routing is fixed:
-
-- Backend services are under `/service`.
-- Platform management UI is under `/platform`.
-- App runtime access is under `/view`.
-
-When the user provides a root domain such as `https://yida.wisejob.cn/`, use it directly with the CLI; OpenXiangda normalizes the API base to `https://yida.wisejob.cn/service`. If the user provides a copied `/platform` or `/view` URL, treat it as the same platform and normalize to `/service`. Do not call `/openxiangda-api/v1` at the root domain.
-
-## Required Flow
-
-1. Ask for the target platform domain if it is not known.
-2. Configure a profile:
-   ```bash
-   openxiangda platform add dev https://dev-lowcode.example.com
-   openxiangda platform use dev
-   ```
-3. If not logged in, run:
-   ```bash
-   openxiangda login --profile dev
-   ```
-   Or combine domain and login:
-   ```bash
-   openxiangda login https://dev-lowcode.example.com --profile dev
-   ```
-4. Check the CLI version and current context before any write:
-   ```bash
-   openxiangda update check --json
-   openxiangda env --profile dev
-   openxiangda auth status --profile dev
-   ```
-   If `updateAvailable` is true, update from the official npm registry before continuing:
-   ```bash
-   openxiangda update install
-   ```
-5. Ensure there is a local app workspace. Local workspace state is authoritative:
-   - If the current workspace already has `.openxiangda/state.json` with an app binding for the target profile, use that app.
-   - If the user explicitly provides an `appType` or asks to reuse an existing app, bind to that exact app.
-   - If the current folder is empty or has no local app binding, create a new app and workspace; do not search the platform for similar app names.
-   ```bash
-   openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
-   cd ./my-app-workspace
-   pnpm install
-   ```
-6. To bind an existing app only when explicitly requested:
-   ```bash
-   openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
-   # or, inside an existing workspace:
-   openxiangda workspace bind --profile dev --app-type APP_XXXX
-   ```
-7. Publish from the local workspace:
-   ```bash
-   openxiangda workspace publish --profile dev
-   ```
-8. For multi-platform publishing, always pass `--profile` explicitly:
-   ```bash
-   openxiangda workspace publish --profile prod
-   ```
-
-## Rules
-
-- Never ask the user for `appKey`, `appSecret`, `AK`, or `SK`.
-- If `openxiangda` is not available in PATH, the CLI package is not installed or linked. In this repo, use `npm link`; in a packaged install, use `npm install -g openxiangda@latest --registry=https://registry.npmjs.org`.
-- Always prefer the official npm registry for OpenXiangda updates. Domestic mirrors may lag and return an older package.
-- Run `openxiangda update check --json` when starting substantial work or diagnosing version/skill mismatches. If it reports an update, run `openxiangda update install` so the CLI and installed skills match. If the installed CLI does not support `update`, run `npm install -g openxiangda@latest --registry=https://registry.npmjs.org` and then `openxiangda skill install --force`.
-- Local `.openxiangda/state.json` is the source of truth for app binding. In an empty folder or unbound workspace, create a new app with `workspace init --app-name`; do not infer reuse from similar platform app names.
-- If there is no `sy-lowcode-app-workspace`, create one with `openxiangda workspace init <dir>` before writing forms, pages, or JS_CODE nodes.
-- Never treat `openxiangda form create` as page generation. It only creates a low-level platform form shell for diagnostics or for workspace publish internals. The source of user-facing pages is `sy-lowcode-app-workspace`.
-- Publish normal form pages, workflow form pages, and custom code pages through `openxiangda workspace publish --profile <name>` from the app workspace.
-- For live platform publishing, do not call `lowcode-workspace publish-all`, `pnpm publish:all`, or legacy project scripts such as `scripts/openxiangda-publish.mjs` directly. They are workspace internals and may miss the normal-user token/profile injection. Use `openxiangda workspace publish ...` so `OPENXIANGDA_PROFILE`, `OPENXIANGDA_BASE_URL`, `OPENXIANGDA_ACCESS_TOKEN`, and `OPENXIANGDA_APP_TYPE` are injected consistently.
-- For routine AI edits, avoid reflexive full publish. First run `openxiangda workspace publish --profile <name> --changed --dry-run`, then use `--changed`, `--page <pageCode>`, `--form <formCode>`, or `--only pages/a,forms/b`. Use full publish only when broad shared/config changes intentionally affect many modules.
-- Never store token data in the project directory. User tokens live in `~/.openxiangda/profiles.json`; project state lives in `.openxiangda/state.json` and stores only IDs and mappings.
-- Shared workspace env values such as `APP_OSS_*` should live in `~/.openxiangda/.env` by default. Project `.env` files are only per-workspace overrides.
-- For custom OSS image or attachment upload, declare `src/resources/storage/<code>.json`, then set `uploadProvider: "oss"` and `storageCode` on `AttachmentField` or `ImageField`. If `imageCompression` outputs `webp` or another explicit format, include that extension in storage `allowedExtensions`.
-- For public/no-login image or attachment uploads, declare `grants.storage` in `src/resources/public-access/<code>.json`; do not open `/service/file/upload` globally. Use conservative private bucket grants by default, with explicit bucket, actions, MIME types, extensions, max size, visibility, and pathPrefix. `ImageField` / `AttachmentField` uploads inside `PublicAccessGate` use the public session bearer token injected by `OpenXiangdaProvider`.
-- For suspected platform defects, bugs, missing capabilities, unclear design rules, repeated workarounds, AI uncertainty, or product optimization requests, proactively run `openxiangda feedback submit --yes` with a concise summary and detailed description. Include the command, error, relevant files, and logs/context files when available. If robot env is missing or submission fails, run/record `openxiangda feedback preview` and tell the user what could not be sent. After successful submission, tell the user what was reported and include the feedback fingerprint. The CLI redacts tokens, cookies, secrets, phone numbers, and emails before sending.
-- For form pages, every visible field should have a concise user-facing `placeholder`. Use `tips` only for special constraints or non-obvious business rules; do not add tips to every field.
-- Form pages should display only fields the user needs to see. Use `SelectField` / `RadioField` for enums. For data maintained by another form, such as class, college, customer, or project, use `SelectField` with `optionSource.type: "linkedForm"` so the runtime queries form data through the SDK and builds dropdown options; set `remoteSearch: true` and an explicit `searchFieldId` when the source data can be large. Do not make users maintain raw ID text fields, and do not use `AssociationFormField` for new form work.
-- Permission scope keys, computed fields, sync fields, and developer/internal fields should be present only when needed for permissions or logic, and should normally be derived from visible select/person/department fields and marked `behavior: "HIDDEN"`. For select-derived scalar keys, use `valueSync`.
-- Do not add extra fields for platform system metadata such as creator, updater, creator department, updater department, created time, or updated time unless the user explicitly needs a separate business field; the platform already creates system fields for each form.
-- All visible copy in forms and pages must be written for end users. Do not put implementation notes, developer explanations, schema descriptions, or "this area is generated by..." text into page sections, cards, labels, tips, or empty states.
-- Use logical resource codes in local files. Platform-specific IDs such as `formUuid`, `pageId`, `workflowId`, and `automationId` must be isolated by profile.
-- Put engineering-managed resources in `src/resources/` and use `openxiangda resource validate|plan|publish|pull`. `workspace publish` publishes workspace forms/pages first, then runs non-destructive resource upsert. Only pass `--prune` when the user explicitly wants local manifests to delete platform-side extras.
-- For repeated read-only multi-form queries or predefined dashboard metrics, create a data view manifest in `src/resources/data-views/`. Use `storageMode: "materialized"` for refreshed lists/reports that tolerate delay; use `storageMode: "live"` for bounded real-time joins where source changes must appear immediately. Use row views plus `sdk.dataView.query` for joined lists/lookups; use `viewType: "aggregate"` plus `sdk.dataView.stats` for count/sum/avg/min/max statistics. Add `indexes` only for materialized views. Do not use data views for single-form CRUD, simple linkedForm selects, writes, write-back, unbounded realtime joins, or ad-hoc BI. Read `references/data-views.md` before designing one.
-- For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.
-- For reusable backend logic shared by pages, automations, and workflows, create an App Function in `src/resources/functions/<functionCode>.json` plus `src/functions/<functionCode>/index.ts`. Call it from pages with `sdk.function.invoke`, from automation/workflow graphs with `function_call`, or from the runtime endpoint. Direct runtime invocation defaults to app automation management permission; ordinary page callers must use `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`). `roleCodes` remains only for current app-role grants; never use `"*"` or `"all-app-roles"` there. Current App Function MVP exposes controlled helpers such as `ctx.resources`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, `ctx.platform.roles`, and `ctx.platform.api`; it does not expose raw SQL or Redis. 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, so unwrap it explicitly if you use it. Runtime functions also receive trusted role context on `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, and `ctx.permissions`; use these for server-side business authorization. Do not trust role codes sent in page input for sensitive actions. App Function form writes are trusted backend writes governed by declared `resources.forms` and function invocation authorization; do not grant normal users raw submit permission to internal forms just to let `ctx.form.createOne/updateOne/updateById` run. For internal function-only forms, publish form settings with `runtimeWrite.mode="function_only"` to close raw write endpoints.
-- For app-managed platform departments/accounts, use `sdk.organization.departments.*`, `sdk.organization.accounts.*`, `ctx.organization.departments.*`, or `ctx.organization.accounts.*`. The real current user/audit actor must hold `app:organization:manage` on the app; runtime service principals do not bypass this permission. Do not call legacy `/user` or `/department` write endpoints from apps. Do not include `password` in account updates; reset target accounts with `resetPassword`, and change the current user's password with `changeMyPassword({ oldPassword, newPassword })`.
-- For account, role, data-scope, organization-account, RBAC, or query-param authorization designs, read `references/permission-design-patterns.md` and choose a permission mode before writing forms/pages/resources. Formal backends should use platform roles, page permission groups, form permission groups, public-access grants, and App Function role/scope checks; frontend hiding is display only.
-- When a role such as 校区管理员 will create app roles, assign role members, grant role permissions, maintain permission groups, or manage organization accounts, its role manifest must declare the needed `apiPermissionCodes` such as `app:role:manage`, `app:page-permission-group:manage`, `app:form-permission-group:manage`, and `app:organization:manage`. If that administrator creates another administrator role, the new role must also declare its own `apiPermissionCodes`; permissions are not inherited from the creator.
-- If `resource publish` reports a missing API permission point such as `app:role:manage`, treat it as a platform seed/data problem. The platform tenant must have the permission code in `api_permissions`; do not remove the role manifest permission just to make publish pass.
-- For application login, declare auth resources in `src/resources/auth/<code>.json` and publish them with `openxiangda resource publish`. App Function auth providers may validate external credentials and return only an identity assertion; they must never issue tokens, set cookies, or write platform user/binding tables directly. The platform auth service decides create/bind/reject and issues tokens.
-- For external/no-login pages in React SPA apps, declare `src/resources/routes/<code>.json` and `src/resources/public-access/<code>.json`, put the page under `/view/:appType/public/*`, and use `PublicAccessGate` or `createPublicAccessClient`. The route tree must also include `OpenXiangdaPageProvider` inside `OpenXiangdaProvider` before any `usePageSdk()` / `usePageContext()` / `useDataSource()` call; otherwise pages throw `usePageSdkStore 必须在 PageProvider 内使用`. Always provide `fallback` and `errorFallback` for public routes so slow networks, missing tickets, or expired tickets do not render blank pages. Public guest access to forms, dataViews, functions, and connectors is denied unless policy `grants` explicitly names the resource; backend permission groups still apply.
-- When verifying public access, parse the response body and reject string business errors such as `PUBLIC_GRANT_DENIED` even if the HTTP status is 200. Do not use `response.ok` alone as the success condition.
-- Before scaffolding a real app, complex page, data management page, portal shell, status lifecycle, role governance, or automation, read `references/best-practices.md` and pick the architecture first. Prefer copying the relevant pattern from `examples/best-practices/` into `src/` instead of generating a single large page file.
-- Before publishing to another platform, verify the workspace is bound for that profile. Resource IDs from one profile must not be reused for another profile.
-- Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` for diagnosis before changing an existing app.
-- Run write commands that update `.openxiangda/state.json` sequentially within the same workspace. Read-only commands can run in parallel.
-- JS_CODE is backend-executed workflow/automation logic, not frontend page code. Use it when logic must run after a backend trigger such as fixed cron schedules, form date-field schedules, form submit/update/delete/field-change events, or workflow approval/process events.
-- 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 end-user task centers, use `sdk.workCenter.listItems({ boxType: "todo" | "done" | "cc" | "initiated" })` and `sdk.workCenter.getStats()` instead of reading workflow logs or process-task tables. 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.
+OpenXiangda connects an AI coding workspace to the private low-code platform through a normal-user profile and `/openxiangda-api/v1`. External backends using AK/SK are a separate `openxiangda-open-api` flow.
 
-## Subskills
+This file is a router and safety card. Read only the one or two subskills selected below; do not load every OpenXiangda reference into the same turn.
+
+## Decide the track
+
+| Intent | Read next | First action |
+| --- | --- | --- |
+| Diagnose, snapshot, compare, explain an error | `openxiangda-inspect` | read-only snapshot/inspect |
+| Login, profile, release, CLI/state issue | `openxiangda-core` | resolve explicit profile and workspace |
+| Create or bind an app | `openxiangda-app` | inspect local binding, then init/bind |
+| Form/schema/data view | `openxiangda-form` | inspect the target form and schema |
+| React/classic page | `openxiangda-page` | inspect the target route/page |
+| Function, automation, workflow, JS_CODE | `openxiangda-workflow-automation` | inspect the exact resource codes |
+| Roles, permission groups, data scope | `openxiangda-permission-settings` | produce the permission matrix |
+| New app architecture, auth, public access | `openxiangda-architecture-design` plus the relevant domain skill | run the design gate |
+| External backend/OpenAPI/AK-SK | `openxiangda-open-api` | describe the exact operation |
+
+## Scope before work
+
+1. Work from the app workspace root and pass `--profile <name>` to every write or release command.
+2. In a shared or dirty checkout, use an isolated Git worktree/branch. `sdd propose|quick|context` automatically claims the current worktree for `CODEX_THREAD_ID`; if another task owns it, stop and move to a separate worktree instead of taking over its files.
+3. Give the task one stable SDD change id. Use `--change <id>` on context, plan, check, verify, publish, and archive commands when supported.
+4. Plan and publish exact resource codes with `--only <codes>` or `--code <code>`; a type-only or full-resource publish is allowed only when the dependency closure intentionally contains the whole type/application.
+5. A React SPA page change rebuilds one application runtime. Commit the complete build input first, upload/preview with `runtime deploy --no-activate`, and promote only from a clean merged release head that descends from the online Runtime source revision.
+
+Never infer a release scope from a globally dirty `git status` when multiple changes are present. Never publish a temporary source tree that differs from the reviewed patch.
+
+## Risk and approval
 
-- `skills/openxiangda-core/SKILL.md`: command workflow and API contract details.
-- `skills/openxiangda-app/SKILL.md`: app creation, binding, snapshots, and profile-isolated workspace state.
-- `skills/openxiangda-architecture-design/SKILL.md`: OpenXiangda-specific architecture design, detailed design, critical review, and development task planning before implementation.
-- `skills/openxiangda-form/SKILL.md`: workspace-based form and workflow form page development, bundle registration, and form publishing.
-- `skills/openxiangda-page/SKILL.md`: custom code page development and publishing in `sy-lowcode-app-workspace`.
-- `skills/openxiangda-workflow-automation/SKILL.md`: workflow v3 definitions, automation triggers, publishing, enabling, and profile-isolated IDs.
-- `skills/openxiangda-permission-settings/SKILL.md`: app roles, page permission groups, form permission groups, and settings-oriented guidance.
-- `skills/openxiangda-inspect/SKILL.md`: read-only app and resource diagnosis using snapshots and profile-local resource IDs.
-- `skills/openxiangda-open-api/SKILL.md`: external backend integration through the complete `/dingtalk-api/v1.0` contract and one-time API credential management.
+- **L0 — no SDD:** read-only diagnosis, docs, tests, or tooling changes that do not mutate an app/platform release.
+- **L1 — lightweight change:** copy/style-only UI edits, a single existing resource binding, or an equally narrow reversible fix. Record exact files/resources and verification. If the user already requested the concrete change after seeing its scope, do not ask for a redundant second confirmation.
+- **L2 — full SDD:** forms/schema, business Function behavior, Automation/Workflow, permissions, auth/public access, data writes/migrations, runtime/config, or multi-resource changes.
+- **L3 — full SDD plus promotion confirmation:** destructive/irreversible operations, production migrations, broad permission/public-access expansion, or an app-wide release.
 
-## API Namespace
+For L2/L3 app work:
 
-OpenXiangda CLI and low-code app development use `/openxiangda-api/v1`. External backend and third-party integrations use `/dingtalk-api/v1.0` through `openxiangda-open-api`; do not switch normal workspace workflows to AK/SK.
+```bash
+openxiangda sdd context --changed --change <change> --json
+openxiangda sdd propose <change>
+# record the user's approval, then:
+openxiangda sdd approve <change>
+openxiangda sdd verify <change> --changed --stage implementation
+```
 
-On private deployments, the public API URL is normally `<platform-domain>/service/openxiangda-api/v1`.
+For an eligible L1 edit, create the exact approved record directly; the user's concrete request is the approval, so do not add a redundant proposal/approval loop:
 
-For external backend integrations, the public base is normally `<platform-domain>/service/dingtalk-api/v1.0`. Use `openxiangda open-api spec describe` for exact request and response fields.
+```bash
+openxiangda sdd quick <change> --kind copy --pages <page> --files <file> --summary "<explicit user intent>"
+```
 
-For endpoint details, read `references/openxiangda-api.md` only when you need request or response fields.
+Function quick changes require the complete `--risk-json` assessment; Automation, Workflow, schema, permissions, auth/public access, migrations, destructive and cross-resource changes cannot use quick mode. Before release run `--stage prepublish`; use `postpublish` only after promotion and `archive` only when all evidence exists.
 
-## References Index
+## Safe release recipes
 
-Load these references on demand instead of memorizing them. Subskills cite the same files with relative paths.
+Classic workspace, exact page/form:
 
-Core CLI / state:
+```bash
+openxiangda workspace plan --change <change> --changed --profile <name> --json
+openxiangda workspace check --change <change> --changed --profile <name>
+openxiangda workspace publish --change <change> --profile <name> --only pages/a,forms/b --dry-run
+openxiangda workspace publish --change <change> --profile <name> --only pages/a,forms/b
+```
 
-- `references/openxiangda-api.md` — `/openxiangda-api/v1` request and response fields, including app-scoped organization APIs.
-- `references/architecture-design.md` — OpenXiangda architecture design gate, anti-pattern rejection, question gates, final design template, and black-box demo scenario.
-- `references/workspace-state.md` — `.openxiangda/state.json` shape and profile isolation rules.
-- `references/connector-resources.md` — `src/resources` manifests, connector schema, App Function boundary, and platform runtime calls.
-- `references/resource-manifest-cheatsheet.md` — 复制即用的 auth / connector / data-view / notification / App Function / workflow / automation / JS_CODE / role / permission group / settings / menu manifest 骨架与运行时调用示例。在创建任何 `src/resources/` 资源前先看这份。
-- `references/data-views.md` — `src/resources/data-views` materialized/live data view resources, DSL, permissions, refresh, CLI commands, and runtime SDK usage.
-- `references/notifications.md` — `src/resources/notifications`, notification templates/type bindings, and `sdk.notification` / `ctx.notification`.
-- `references/best-practices.md` — initialized examples for modular pages, state lifecycles, role governance, permission isolation, high-performance queries, portal shells, workflow boundaries, and automation patterns.
-- `references/permission-design-patterns.md` — account/role/permission design modes: managed platform account, existing user assignment, static role permission, query-param context, and the required resource/permission matrix.
+React SPA resources/runtime:
 
-Form authoring:
+```bash
+openxiangda resource validate <type> --only <codes> --profile <name>
+openxiangda resource plan <type> --only <codes> --profile <name> --json
+openxiangda runtime deploy --change <change> --profile <name> --no-activate --json
+openxiangda sdd verify <change> --changed --stage prepublish
+openxiangda release begin --change <change> --profile <name>
+openxiangda resource publish <type> --only <codes> --change <change> --profile <name>
+openxiangda runtime activate <reviewedReleaseId> --change <change> --profile <name>
+openxiangda release end --profile <name>
+```
 
-- `references/forms/form-schema.md` — `defineFormSchema` structure, field types, top-level effects.
-- `references/forms/component-registry.md` — supported form components and their props.
-- `references/forms/layout-and-rules.md` — layout containers, field rules, and validation patterns.
+`resource plan` and publish dry-runs are strictly GET/HEAD-only. `READ_ONLY_AUTH_REQUIRED` means the access token expired; run `openxiangda auth refresh --profile <name>` or log in again before retrying. Never add an automatic refresh POST inside a plan.
 
-Page authoring:
+`release begin --change` freezes the reviewed Git source base plus the selected remote change baseline. Before any live write, the CLI preflights the complete target set. A worktree based on obsolete source fails with `SOURCE_BASE_DIVERGED`; a selected remote field changed after the baseline fails with `RESOURCE_FIELD_CONFLICT`. Resolve/merge, rebuild, and re-plan instead of forcing the old release.
 
-- `references/pages/workspace-structure.md` — `src/pages/<pageCode>/` layout and config.
-- `references/pages/page-sdk.md` — `openxiangda/runtime` data, connector, data view, notification, organization, and App Function APIs.
-- `references/pages/publish-flow.md` — workspace publish steps for code pages.
+`runtime deploy` separately freezes the clean committed `HEAD` as `sourceRevision` together with the current active Runtime parent before any build or upload. Any deploy whose source does not descend from the online Runtime fails with `RUNTIME_SOURCE_BASE_DIVERGED`, including `--no-activate`; this prevents staging an old preview for later activation. `--no-build` does not bypass this guard. Only an intentional audited rollback may use `--allow-runtime-rollback --reason "<at least 8 characters>"`, and that flag never permits dirty or non-Git input. SDD evidence under `openspec/` and generated/state paths do not make Runtime source dirty.
 
-Workflow / automation / permissions:
+For a whole-app release, keep changed Runtime/Page/Backend/Form children staged and run `openxiangda release app-finalize --change <change> --staged-resources-json <JSON|file> --profile <name>`. The JSON contains only changed immutable child entries; the CLI overlays Runtime/Page/Backend by singleton kind and FormRelease by `formUuid` onto one authoritative read-only capture, preserving every unmodified active child. It then performs `prepare -> verify -> activateStagedChildren=true`, switching child heads and the App head atomically (`atomic_staged_children_v1`). Never refresh or retry after a conflict. The flow requires the owned stored lease/change baseline and carries the same client session and Git lineage on every write. Omitting the overlay is compatibility-only retrospective aggregation of already-active children.
 
-- `references/workflow-v3.md` — workflow v3 definitions, JS_CODE nodes, App Function `function_call`, and trusted_node mode.
-- `references/automation-v3.md` — automation triggers, conditions, App Function `function_call`, and publishing.
-- `references/permissions-settings.md` — roles, page/form permission groups, settings.
-- `references/permission-design-patterns.md` — required when designing accounts, roles, RBAC, organization-account governance, data scope, or query-param authorization.
+When a Function or Automation is selected because its TypeScript source changed, publishing is source-only by default. Eligible existing Function/Automation updates in the same command use one immutable Backend Release (`prepare -> verify -> activate`) and one database transaction, so a stale member produces zero resource writes and noops do not advance versions/timestamps. Online bindings, input/output contracts, metadata, trigger/view configuration, and enabled/published state remain unchanged. Only an explicit Backend Release `head` HTTP 404 permits the warned compatibility source PATCH. A complete manifest replacement is exceptional and requires exact `--only/--code` plus `--replace-manifest --reason "..."`.
 
-Platform domain knowledge (read these first when generating forms or pages so the output matches the live platform behavior):
+The lease is app-level promotion ownership, while worktree ownership prevents two Codex tasks from editing/publishing through the same source directory. Different worktrees may keep developing and validating. Always run `release end` after promotion or abandonment; stale sessions expire automatically. Use full resource/runtime publish only when the approved dependency closure is app-wide.
+
+## Always
+
+- Treat `.openxiangda/state.json` as CLI-maintained ID mapping, not a task lock or merge mechanism.
+- Keep resource IDs isolated per profile; never copy IDs from dev to prod.
+- Use platform roles, permission groups, public grants, and backend Function checks for authorization; frontend hiding is presentation only.
+- Keep tokens and secrets out of project files and chat.
+- Use official public SDK entrypoints and platform form/file components.
+- Report platform defects or repeated workarounds with `openxiangda feedback submit --yes` when a configured feedback channel is available.
+- Run `openxiangda update check --json` once at the start of substantial work, when a version mismatch is suspected, or when the cached check is older than one day. Do not repeat it on every confirmation turn.
+
+## Never
+
+- Do not call `pnpm publish:all`, `pnpm publish:oss`, `pnpm register`, or `lowcode-workspace publish-*` as the live entrypoint.
+- Do not omit `--profile` on writes/releases.
+- Do not run an unscoped full publish after a narrow edit.
+- Do not use query parameters, hard-coded roles, fake IDs/data, or UI visibility as sensitive authorization.
+- Do not ask the user to paste AK/SK/app secrets. Normal work uses the user profile; external integrations use the dedicated credential flow.
+- Do not import SDK internals or hand-build legacy React SPA public/workbench routes.
+
+## Subskills
 
-- `references/platform-data-model.md` — how the platform persists field values (JSONB, `{label, value}` for option fields, attachment shape, etc.). Use this whenever you write, render, or diagnose form data.
-- `references/style-system.md` — style isolation defaults, legacy namespace compatibility, and flexible Tailwind/CSS guidance. Use this before writing substantial page or form CSS.
-- `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, recommended directory layout for `src/pages` and `src/forms`. Use this before scaffolding a new page or list view.
-- `references/best-practices.md` — read this before implementing app-level business patterns; it points to `examples/best-practices/` and explains when to use status fields instead of workflow.
-- `references/component-guide.md` — component priority ladder: platform components first, `antd` / `antd-mobile` fallback, and no raw native form controls in AI-authored app code. Use this before introducing a new component.
-- `references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and how to fix them. Use this when something does not behave as expected.
+- `../openxiangda-core/SKILL.md`
+- `../openxiangda-app/SKILL.md`
+- `../openxiangda-architecture-design/SKILL.md`
+- `../openxiangda-form/SKILL.md`
+- `../openxiangda-page/SKILL.md`
+- `../openxiangda-workflow-automation/SKILL.md`
+- `../openxiangda-permission-settings/SKILL.md`
+- `../openxiangda-inspect/SKILL.md`
+- `../openxiangda-open-api/SKILL.md`
+
+Load a reference only when the selected subskill explicitly requires it. Workspace `AGENTS.md` remains authoritative for project-specific constraints.

package/openxiangda-skills/references/architecture-design.md

@@ -186,7 +186,7 @@ Default: reusable calculations and validations become App Functions; one-off bac
 
 Ask these before generating any login/auth design:
 
-- Which methods are enabled: password, DingTalk in-app free login, CAS/SSO, phone code, guest?
+- Which methods are enabled: password, DingTalk browser OAuth/in-app free login, CAS/SSO, phone code, guest?
 - What is the phone registration policy: reject, auto-create, bind existing only, whitelist, or manual approval?
 - What are the identity match keys and priorities: `phone`, `email`, `externalId`, `unionId`, `jobNumber`, `username`?
 - Which App Function provider validates each external credential, and what identity assertion fields must it return?
@@ -280,6 +280,7 @@ For simple CRUD/admin lists, design can proceed with the appropriate OpenXiangda
 - Auth resources use stable local codes under `src/resources/auth/`.
 - Use `/view/:appType/login` or `LoginPage` from `openxiangda/runtime/react` for default React login.
 - Use `createAuthClient({ appType, servicePrefix })` for custom React login pages.
+- DingTalk `flow: "auto"` uses JSAPI only in a confirmed DingTalk container and otherwise starts platform-managed browser OAuth. The platform owns callback state and secrets; app code supplies only an app-local `returnUrl` through `getDingTalkOAuthUrl`.
 - Phone-code providers are App Functions. They validate send/verify events and return identity assertions; they do not issue tokens or mutate platform users.
 - New-user registration must be explicit, with default roles and identity conflict behavior documented.
 

package/openxiangda-skills/references/openxiangda-api.md

@@ -78,6 +78,33 @@ Body:
 
 Requires Bearer token. Revokes the current CLI token session.
 
+## App Runtime Auth
+
+### POST `/apps/:appType/auth/dingtalk/oauth/start`
+
+Starts platform-managed DingTalk browser OAuth for an application. This endpoint is called without an existing app login session. The platform creates and stores one-time callback state; application code must not build the DingTalk authorization URL itself.
+
+Body:
+
+```json
+{
+  "returnUrl": "/view/APP_EXAMPLE/admin"
+}
+```
+
+`returnUrl` is optional and, when present, must stay under the current application's `/view/:appType/*` routes.
+
+Response data:
+
+```json
+{
+  "loginUrl": "https://login.dingtalk.com/oauth2/auth?...",
+  "expiresIn": 600
+}
+```
+
+The platform-owned callback consumes the one-time state, creates the authenticated platform session, and redirects to the validated `returnUrl`. React applications normally use `LoginPage dingtalkFlow="auto"`; custom login pages call `createAuthClient(...).getDingTalkOAuthUrl({ returnUrl })` and navigate to `loginUrl`.
+
 ## App Snapshot
 
 ### GET `/apps/`

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

@@ -247,7 +247,7 @@ Application auth:
 import { LoginPage, useAuth, useLoginMethods } from "openxiangda/runtime/react";
 
 export function DefaultLogin() {
-  return <LoginPage />;
+  return <LoginPage dingtalkFlow="auto" />;
 }
 
 export function CustomPhoneLogin() {
@@ -269,6 +269,14 @@ import { createAuthClient } from "openxiangda/runtime";
 
 const auth = createAuthClient({ appType, servicePrefix: "/service" });
 const methods = await auth.getMethods();
+
+async function startDingTalkLogin() {
+  const { loginUrl } = await auth.getDingTalkOAuthUrl({
+    returnUrl: `/view/${encodeURIComponent(appType)}/admin`,
+  });
+  window.location.assign(loginUrl);
+}
+
 const sent = await auth.sendPhoneCode({ phone, purpose: "login" });
 const result = await auth.phoneCodeLogin({
   phone,
@@ -277,6 +285,8 @@ const result = await auth.phoneCodeLogin({
 });
 ```
 
+`dingtalkFlow="auto"` is the default. It uses DingTalk JSAPI only when both the container and `requestAuthCode` are available; otherwise it starts browser OAuth. Explicit `dingtalkFlow="jsapi"` or `"oauth"` overrides the auth method's `flow` setting. Browser OAuth is a full-page redirect whose callback is handled by the platform, so custom pages should pass an app-local `/view/:appType/*` return URL and must not implement their own callback or OAuth `state`. `LoginPage` normalizes a same-origin absolute guard callback to that relative form and rejects cross-origin or other-app callbacks before making the OAuth start request.
+
 For phone-code auth, the App Function provider receives `event`, `appType`, `method`, `credential`, `requestId`, `request`, and `challenge`. It may return `{ ok, providerState }` for send and `{ ok, identity }` for verify. It must not return `token`, `accessToken`, `refreshToken`, cookies, or mutate platform account tables.
 
 Public access route:

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

@@ -74,7 +74,7 @@ openxiangda permission role-update external_visitor --json-file src/resources/ro
   "configJson": {
     "methods": [
       { "type": "password", "enabled": true, "label": "账号密码" },
-      { "type": "dingtalk", "enabled": true, "label": "钉钉免登" },
+      { "type": "dingtalk", "enabled": true, "label": "钉钉登录", "flow": "auto" },
       { "type": "sso", "enabled": true, "label": "CAS", "protocol": "cas" },
       {
         "type": "phone_code",
@@ -127,7 +127,7 @@ React 默认页：
 import { LoginPage } from "openxiangda/runtime/react";
 
 export default function AppLogin() {
-  return <LoginPage />;
+  return <LoginPage dingtalkFlow="auto" />;
 }
 ```
 
@@ -138,10 +138,20 @@ import { createAuthClient } from "openxiangda/runtime";
 
 const auth = createAuthClient({ appType, servicePrefix: "/service" });
 const methods = await auth.getMethods();
+
+async function startDingTalkLogin() {
+  const { loginUrl } = await auth.getDingTalkOAuthUrl({
+    returnUrl: `/view/${encodeURIComponent(appType)}/admin`,
+  });
+  window.location.assign(loginUrl);
+}
+
 const sent = await auth.sendPhoneCode({ phone, purpose: "login" });
 await auth.phoneCodeLogin({ phone, code, challengeId: sent.challengeId });
 ```
 
+钉钉 `flow: "auto"` 会在确认处于钉钉容器且 JSAPI 可用时走免登，否则走平台托管的浏览器 OAuth。`returnUrl` 只能是当前应用的 `/view/:appType/*` 路径；应用不要自行拼装钉钉授权 URL、保存 OAuth `state` 或实现回调页。
+
 设计前必须确认启用方式、注册策略、身份匹配键、provider 边界、默认权限、安全参数、第三方配置归属。
 
 ## 1. Storage — `src/resources/storage/<code>.json`

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

@@ -62,5 +62,7 @@ Tokens never belong in the project. User tokens live in `~/.openxiangda/profiles
 - `resources.dataViews` is keyed by data view `code` and stores only profile-local platform metadata such as `dataViewId`, `materializedViewName`, and last known `status`.
 - 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.
 - Before publishing to another platform, run `openxiangda workspace bind --profile <name> --app-type <APP_XXX>`.