openxiangda 1.0.268 → 1.0.270

package/README.md

@@ -22,6 +22,21 @@ Normal OpenXiangda app development uses platform-user login tokens through `/ope
 
 Private platform routing is fixed: backend APIs are under `/service`, platform management is under `/platform`, and app runtime access is under `/view`. Passing a root domain such as `https://platform.example.com/` to the CLI is supported; OpenXiangda stores the API base as `https://platform.example.com/service`.
 
+## 升级到 OpenXiangda 2.0
+
+建议评估升级到 OpenXiangda 2.0；新应用优先使用 V2，现有应用先确认能力覆盖、迁移成本与验收方案。准备 Node.js 24+，安装最新统一入口：
+
+```bash
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+# 进入原 V1 项目，使用新版全局入口
+openxiangda version --json
+openxiangda migrate assess --to v2 --json
+```
+
+`latest` / `stable-v2` 是 V2 稳定渠道，`legacy-v1` 是 V1 维护渠道。统一入口继续用原项目的 V1 引擎；不会自动迁移配置、数据或流程。V1 项目用 `openxiangda update install --target workspace` 更新同代维护版；全局入口用 `--target launcher` 更新。项目锁定的 V1 CLI 不提供 `migrate` 命令，评估时使用新版全局命令。
+
+版本查询、更新检查/安装、Skill 安装后会展示建议；JSON 调用通过 `migrationAdvice` 字段提供同样信息。CLI、Skill、MCP 如何安装、刷新以及配置客户端，见[统一安装升级说明](https://github.com/1377385356/openxiangda/blob/master/docs/getting-started.md#upgrade)。工具更新与应用迁移分别执行。
+
 ## OpenXiangda 1.x Delivery V2 (maintenance)
 
 New workspaces declare `deliveryVersion: 2`. The release flow is intentionally
@@ -150,7 +165,7 @@ 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 durable profile-specific resource IDs and environment bindings; volatile candidate/deployment progress lives in the private `.openxiangda/releases/` journal so a release does not dirty the reviewed Git state. Durable CLI writes use a workspace lock plus atomic merge/rename so concurrent processes do not truncate another profile's state.
+User tokens are stored in the current workspace `.openxiangda/profiles.json` with `0600` permissions and automatic Git ignore rules. Global profiles are no longer read or merged; sign in again in each project after upgrading. Use `login --cwd <directory>` to select a new project explicitly. 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 durable profile-specific resource IDs and environment bindings; volatile candidate/deployment progress lives in the private `.openxiangda/releases/` journal so a release does not dirty the reviewed Git state. Durable CLI writes use a workspace lock plus atomic merge/rename so concurrent processes do not truncate another profile's state.
 
 An environment-managed workspace keeps one logical application with independent `preproduction` and `production` targets. Each target owns its own `appType`, resource IDs, release heads, data, and side-effect policy; IDs must never be copied across targets. `release ship` always executes the same ordered candidate → preproduction → production protocol. The normal first invocation seals the candidate, deploys only to preproduction, and stops at `awaiting_production_confirmation`; a later invocation with `--confirm-production` promotes it. For an explicitly authorized emergency, supplying `--confirm-production` on the first invocation runs both phases in one command without bypassing preproduction, CAS, evidence, or production confirmation. Candidate sealing covers source, `public/`, build controls/scripts, stable environment/resource bindings, and target-specific hashed Runtime artifacts. Both deployments upload those artifacts with `--no-build`; Backend, Runtime, and Root children all retain the sealed candidate `sourceRevision`, even when promotion starts from a later clean descendant mainline commit. Each deployment is completed with evidence and reaches terminal `succeeded`, so it cannot leave the target slot blocked. Unrelated commits may land on authoritative mainline between phases only while the sealed commit remains an ancestor and every sealed input/binding/artifact still validates. Real human acceptance remains the recommended default and `--acceptance-note` records it. For audited historical-lineage adoption or reviewed Backend manifest replacement, the existing paired flags and exact-scope gates remain mandatory. Supported configuration resources use exact `resourceSelectors`; unknown, wildcard, destructive, and genuinely unscoped generic resources remain blocked. Lower-level candidate/deploy/test/fail/promote commands are recovery primitives. `release fail` requires an explicit preproduction target, deployment ID, and audit message; it verifies the deployment belongs to that preproduction environment before writing optional code/details to the platform failure audit. Direct `release publish` is retained only for legacy unmanaged workspaces.
 
@@ -602,6 +617,8 @@ const PublicAccessError = ({ error }: { error: { message?: string } }) => (
 
 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 会失败关闭，绝不忽略绑定。
 
+外部系统主动调用应用时，在 `src/resources/webhooks/<code>.json` 声明 Inbound Webhook 和固定 `targetFunctionCode`，用 `openxiangda resource validate|plan|publish webhook` 发布。平台返回的 `callbackPath` 是公开回调路径；不要用租户内的 `appType` 自行拼接入口。目标 Function 在顶层 `secretRefs` 声明供应商 Secret，并且必须先基于精确 `input.rawBody` 验签，再访问表单、数据视图、连接器、通知或外部 HTTP；投递是 at-least-once，业务写入还要用 `input.idempotencyKey` 做原子幂等。使用 `openxiangda webhook deliveries|delivery` 查看投递状态和原始请求审计，完整契约见 `openxiangda-skills/references/webhooks.md`。
+
 平台部门和账号管理走 app-scoped organization 能力。只读查询要求目标应用的 `app:organization:read` 或 `app:organization:manage`，创建、更新和密码操作要求 `app:organization:manage`；平台管理员天然可用，普通应用角色需要显式授权。Runtime service principal 不会直接放行，`ctx.organization` 会按真实操作人 / audit actor 校验权限。新接口不提供删除；`account-update` 不能携带 `password`，重置他人密码必须走 `account-reset-password`，当前用户改密用 SDK / `ctx.organization.accounts.changeMyPassword({ oldPassword, newPassword })`。
 
 CLI 写操作必须加 `--force`：
@@ -685,3 +702,5 @@ 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).
+
+平台登录态只使用当前工作区的 `.openxiangda/profiles.json`，不再读取或合并用户主目录的全局 profiles。升级后请进入每个项目运行 `openxiangda login <platform-url>`；子目录沿最近应用根目录定位，不跨嵌套应用或 Git 边界。登录文件及临时文件会自动加入忽略规则，请勿提交或打包。新项目先用 `openxiangda login <platform-url> --cwd <directory>` 在目标目录登录，再在该目录运行 `openxiangda workspace init`。