openxiangda 1.0.159 → 1.0.161

package/README.md

@@ -33,22 +33,32 @@ openxiangda data-view list --profile dev
 openxiangda data-view status ticket_with_customer --profile dev
 openxiangda doctor --profile dev --json
 openxiangda design gates --topic public-access --json
-openxiangda sdd context --json
+openxiangda sdd context --change add-customer-page --changed --json
 openxiangda sdd propose add-customer-page --pages customer --runtime
 openxiangda sdd approve add-customer-page --summary "用户确认"
-openxiangda sdd verify add-customer-page --changed
-openxiangda resource validate --profile dev
-openxiangda resource plan --profile dev
-openxiangda resource publish --profile dev
+openxiangda sdd verify add-customer-page --changed --stage implementation
+openxiangda resource validate function --only customer_get,customer_save --profile dev
+openxiangda resource plan function --only customer_get,customer_save --profile dev
+openxiangda runtime deploy --change add-customer-page --profile dev --no-activate --json
+openxiangda sdd verify add-customer-page --changed --stage prepublish
+openxiangda release begin --change add-customer-page --profile dev
+openxiangda resource publish function --only customer_get,customer_save --change add-customer-page --profile dev
+openxiangda runtime activate <reviewedReleaseId> --change add-customer-page --profile dev
+openxiangda release end --profile dev
 openxiangda resource explain public-access --json
-openxiangda runtime deploy --profile dev
 openxiangda inspect app --profile dev --json
 openxiangda app snapshot APP_XXXX --profile dev --json
 ```
 
-User tokens are stored in `~/.openxiangda/profiles.json` with `0600` permissions. Shared workspace environment values, including `APP_OSS_*`, can live in `~/.openxiangda/.env` and are inherited by new workspaces. Project `.env` files still work and override the global defaults. Project state is stored in `.openxiangda/state.json` and contains only profile-specific resource IDs.
+User tokens are stored in `~/.openxiangda/profiles.json` with `0600` permissions. Shared workspace environment values, including `APP_OSS_*`, can live in `~/.openxiangda/.env` and are inherited by new workspaces. Project `.env` files still work and override the global defaults. Project state is stored in `.openxiangda/state.json` and contains only profile-specific resource IDs; CLI writes use a workspace lock plus atomic merge/rename so concurrent processes do not truncate another profile's state.
+
+`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.
 
-React SPA workspaces publish their frontend with `openxiangda runtime deploy`. The default upload mode is `auto`: it tries staged multipart first, then falls back to built-in OSS direct upload if the staged file API returns HTTP 403. Use `--upload-mode oss-direct` to force built-in OSS direct upload, or `--upload-mode legacy-json` only as a compatibility fallback for older platforms. Upload progress, timeout, and `traceId` are written to stderr; `--json` stdout remains the final JSON result. Use `--upload-timeout-ms <ms>` or `OPENXIANGDA_RUNTIME_UPLOAD_TIMEOUT_MS` to tune runtime upload/finalize timeouts.
+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.
+
+Concurrent development may still upload immutable previews with `--no-activate`, but the preview must also freeze a real clean Git source revision before it can become a release. Final promotion uses `release begin/end` so one `(tenant, app)` has one writer while other worktrees keep developing and testing. `release begin --change <change>` binds the per-task `clientSessionId` (Codex uses `CODEX_THREAD_ID`) and freezes both the reviewed Git source base and the selected remote resource-field heads. Before the first live write, the CLI preflights the complete selected set. A stale resource worktree fails with `SOURCE_BASE_DIVERGED`; a selected remote field that moved after the baseline fails with `RESOURCE_FIELD_CONFLICT`. Resolve the divergence, rebuild/re-plan, and start a new release instead of retrying a stale payload. The default upload mode is `auto`: it tries staged multipart first, then falls back to built-in OSS direct upload if the staged file API returns HTTP 403. Use `--upload-mode oss-direct` to force built-in OSS direct upload, or `--upload-mode legacy-json` only as a compatibility fallback for older platforms. Upload progress, timeout, and `traceId` are written to stderr; `--json` stdout remains the final JSON result.
+
+Source-triggered Function and Automation publishing is source-only by default. On a current platform, every eligible existing Function and Automation in one command is uploaded, prepared, verified, and activated through one immutable Backend Release transaction; a stale target therefore causes zero resource writes instead of failing halfway through 88 Functions and 11 Automations. The release preserves online `resourceBindings`, input/output contracts, descriptive metadata, trigger/view configuration, and enabled/published state, and planned noops do not advance resource versions or timestamps. Only an older platform whose Backend Release `head` route explicitly returns HTTP 404 uses the compatibility per-resource source PATCH, with a warning on stderr. To intentionally make a complete local manifest replace the online definition, select exact codes and opt in explicitly with `--replace-manifest --reason "<why this replacement is safe>"`; `--sdd-bypass` does not widen that scope.
 
 React SPA templates include stable Vite manual chunk grouping for React, antd, ECharts, editor dependencies, and OpenXiangda runtime/component entrypoints. The SDK keeps large UI dependencies such as `antd-mobile` and `dayjs` external so the application bundler can split them by route. Applications should import from public package entrypoints such as `openxiangda`, `openxiangda/runtime`, and `openxiangda/runtime/react`; do not import `openxiangda/packages/sdk/dist/...` internals to chase bundle size.
 
@@ -82,7 +92,9 @@ Domestic npm mirrors may lag and return an older OpenXiangda version. `openxiang
 
 Architecture-class requests are plan-gated by default. For new apps, complex pages, login/register, public/no-login access, role/data-scope design, workflow/automation, App Function, connector, notification, and external integration work, AI agents must plan first and implement only after the user confirms the design.
 
-High-risk implementation is also SDD-gated. New workspaces include OpenXiangda SDD v2 records under `openspec/` by default. Before changing forms, pages, resources, functions, automations, workflows, JS_CODE nodes, runtime code, or `app-workspace.config.ts`, run `openxiangda sdd context --json`, create or continue a change with `openxiangda sdd propose <change>`, and wait for `openxiangda sdd approve <change>`. `approve` only opens the implementation gate; release checks also require `coverage.json`, `release.json`, `evidence.md`, `tasks.md`, and delta specs to pass `openxiangda sdd verify <change> --changed`. Emergency releases can use `--sdd-bypass --reason "..."`, which writes `openspec/changes/bypass-log.md` and appends bypass evidence to the active approved change when one exists.
+Risk is tiered. Read-only/docs/tests are L0. Narrow reversible copy/style or single existing binding fixes are L1 and use `openxiangda sdd quick` to record exact files/resources plus the user's already-explicit intent; do not add a second proposal/approval ceremony to such a small change. Function quick fixes additionally require the complete negative risk assessment. Schema, business Functions, Automation/Workflow, permissions, auth/public access, data writes, and runtime/config are L2; irreversible production or app-wide changes are L3. L2/L3 use an explicit SDD change from context through plan/check/verify/publish/archive. Run `verify --stage implementation` while developing, `prepublish` before promotion, `postpublish` after live probes, and `archive` only with complete evidence. Emergency releases can still use `--sdd-bypass --reason "..."` and remain auditable.
+
+Every concurrent task should use its own Git worktree/branch. `sdd propose|quick|context` automatically claims the current worktree for the active `CODEX_THREAD_ID`; a second task receives `WORKTREE_OWNED_BY_ANOTHER_TASK` before it can publish through the shared directory. Inspect or explicitly release ownership with `openxiangda workspace ownership status|release`; forced takeover requires a reason. Live `resource publish` requires exact `--only <codes>` or `--code <code>`; an app-wide publish needs explicit `--all --reason`, even when SDD is bypassed. The approved change scope, not the checkout's global dirty set, is the release boundary.
 
 Before confirmation, agents may read, inspect, snapshot, dry-run, ask questions, and output/write the architecture document. They must not edit source files, mutate platform resources, publish, deploy, send notifications, or call live write/delete endpoints.
 
@@ -98,11 +110,21 @@ openxiangda commands --json
 For formal multi-resource development, keep the repository as the source of truth and use `src/resources/**`:
 
 ```bash
-openxiangda resource validate --profile dev
-openxiangda resource plan --profile dev
-openxiangda resource publish --profile dev
+openxiangda resource validate function --only customer_get,customer_save --profile dev
+openxiangda resource plan function --only customer_get,customer_save --profile dev
+openxiangda resource publish function --only customer_get,customer_save --change <change> --profile dev
+
+# Only for an intentional whole-definition replacement:
+openxiangda resource publish function --code customer_get --change <change> --profile dev \
+  --replace-manifest --reason "reviewed manifest is the complete desired definition"
 ```
 
+For source-only Function/Automation changes, the final command does not reconstruct whole definitions with client-side GET+PUT. `release begin` captures the Git/change baseline, one preflight covers every selected code, and Backend Release performs one `prepare -> verify -> activate` sequence for all eligible updates. Inspect history with `openxiangda release backend-head|backend-list|backend-detail`, compare it with `backend-diff`, or create an audited immutable rollback with `backend-rollback <releaseId> --change <change> --reason "..."`. Always run `release end` when promotion finishes or is abandoned.
+
+Page repair publishing is staged by default. It first freezes `pages/snapshot`, sends the active Page Release parent plus every page revision, and uses revision `0` only for a genuinely new page. Review with `openxiangda page head|releases|detail|diff`; activate an immutable complete release explicitly with `page activate <releaseId> --change <change>`. Historical activation requires `page rollback <releaseId> --rollback --change <change> --reason "..."`. Parent or revision conflicts are never refreshed or retried automatically.
+
+Use `openxiangda release app-capture` to read the platform's transactionally consistent whole-app manifest. For a normal multi-resource release, stage the changed Runtime/Page/Backend/Form child releases, write only their immutable entries (`kind`, `identity.releaseId`, `hash`, plus `identity.formUuid` for forms) to a JSON array, then run `app-finalize --change <change> --staged-resources-json <JSON|file>`. The CLI overlays Runtime/Page/Backend by singleton kind and Form by `formUuid`, preserves every unmodified active child from the read-only capture, and sends the complete frozen manifest through `prepare -> verify -> activate` with `activateStagedChildren=true`. The child heads and App head therefore switch in one database transaction (`atomic_staged_children_v1`); any parent, revision, asset, or hash drift stops with zero root activation and is never refreshed or retried. `app-prepare` accepts the same overlay for a manual reviewed flow, and `app-activate <releaseId> --activate-staged-children` performs the explicit atomic activation. Calling `app-finalize` without an overlay remains a compatibility-only retrospective aggregation of already-active children. `app-rollback <releaseId> --change <change> --reason "..."` prepares the audited rollback manifest.
+
 For small live fixes, diagnosis, or AI command discovery, use first-class resource commands. They all accept `--profile`, `--app-type`, `--json`, `--json-file`, `--dry-run`, and write commands can use `--write-manifest` to avoid repo/platform drift:
 
 ```bash
@@ -439,7 +461,7 @@ await ctx.organization.accounts.resetPassword("user-alice", {
 })
 ```
 
-应用登录能力通过 auth resource 和 runtime SDK 提供：登录配置放在 `src/resources/auth/<code>.json`，默认 React SPA 模板已包含 `/view/:appType/login`，自定义页面可使用 `createAuthClient({ appType, servicePrefix })` 或 `LoginPage` / `useAuth` from `openxiangda/runtime/react`。手机号验证码、CAS/SSO 或其他外部登录可以由 App Function provider 校验外部凭证，但 provider 只能返回 `phone` / `email` / `externalId` / `unionId` 等身份声明；平台后端按 auth resource 策略执行账号匹配、绑定、创建或拒绝，并由平台统一签发 token/cookie。默认注册策略是拒绝，开启自动注册或白名单注册前必须确认身份匹配键、默认角色、验证码 TTL/频率/失败次数、审计字段和错误文案策略。
+应用登录能力通过 auth resource 和 runtime SDK 提供：登录配置放在 `src/resources/auth/<code>.json`，默认 React SPA 模板已包含 `/view/:appType/login`，自定义页面可使用 `createAuthClient({ appType, servicePrefix })` 或 `LoginPage` / `useAuth` from `openxiangda/runtime/react`。钉钉登录默认使用 `dingtalkFlow="auto"`：只有明确位于钉钉容器且 JSAPI 可用时才走免登码，普通浏览器会请求应用级 OAuth 地址并跳转钉钉认证页；自定义页可调用 `getDingTalkOAuthUrl({ returnUrl })` 接入相同能力。手机号验证码、CAS/SSO 或其他外部登录可以由 App Function provider 校验外部凭证，但 provider 只能返回 `phone` / `email` / `externalId` / `unionId` 等身份声明；平台后端按 auth resource 策略执行账号匹配、绑定、创建或拒绝，并由平台统一签发 token/cookie。默认注册策略是拒绝，开启自动注册或白名单注册前必须确认身份匹配键、默认角色、验证码 TTL/频率/失败次数、审计字段和错误文案策略。
 
 常用数据视图命令：
 
@@ -476,3 +498,7 @@ AI-authored workflows can use compile-time SDK resources:
 Resource and connector manifest guide: [docs/openxiangda-resources-and-connectors.md](docs/openxiangda-resources-and-connectors.md).
 
 Skill migration plan: [docs/skill-refactor-plan.md](docs/skill-refactor-plan.md).
+
+Release isolation and speed roadmap: [docs/release-isolation-and-speed-roadmap.md](docs/release-isolation-and-speed-roadmap.md).
+
+Reproduced concurrency incidents and regression invariants: [docs/release-concurrency-incident-matrix.md](docs/release-concurrency-incident-matrix.md).