openxiangda 1.0.269 → 1.0.271

package/openxiangda-skills/references/webhooks.md

@@ -0,0 +1,213 @@
+# OpenXiangda 1.x Inbound Webhooks
+
+Inbound Webhook 用于让门禁、支付、IoT 等外部系统主动调用 OpenXiangda
+应用。平台只负责通用接入：接收和保存原始请求、限制大小、按幂等键串行化、
+调用唯一绑定的 App Function，并把 Function 的处理结果映射为稳定 HTTP 状态。
+供应商签名规则、事件筛选和业务写入始终属于应用 Function。
+
+## 声明 Webhook
+
+在 `src/resources/webhooks/<code>.json` 创建 Manifest：
+
+```json
+{
+  "code": "yuquan_access",
+  "name": "玉泉门禁开门事件",
+  "description": "接收 REC_SUCCESS 事件并匹配琴房预约",
+  "targetFunctionCode": "qfyy_access_event",
+  "idempotencyQueryParam": "nonce",
+  "maxBodyBytes": 262144,
+  "status": "active"
+}
+```
+
+- `targetFunctionCode` 必须是同一租户、同一应用内已经启用的 Function。
+- `idempotencyQueryParam` 默认是 `nonce`。该参数为空时，平台使用请求摘要。
+- `maxBodyBytes` 默认 256 KiB，允许范围为 1 KiB 到 1 MiB。
+- 平台网关对公开入口统一限制 1 MiB，并按来源 IP 限制 100 请求/秒、突发
+  200；超限返回 429。该限制不代替验签和业务幂等。
+- Manifest 不得包含 Webhook Secret、签名算法或供应商凭据。
+- 发布后从 `.openxiangda/state.json` 的
+  `resources.webhooks.<code>.callbackUrl` 取得完整回调地址；`callbackPath` 是相对
+  当前 profile API base（通常为 `<origin>/service`）的路径。不要自行用 `appType`
+  拼接公开 URL。
+
+## 声明和配置 Secret
+
+Webhook Secret 使用现有 App Function Secret。Function 必须使用
+`function_v2 + trusted_node_v2`，并在 Manifest 顶层声明引用：
+
+```json
+{
+  "code": "qfyy_access_event",
+  "name": "处理玉泉门禁事件",
+  "secretRefs": [
+    { "name": "yuquan_webhook_secret", "required": true }
+  ],
+  "definitionJson": {
+    "version": "function_v2",
+    "runtimeMode": "trusted_node",
+    "runtimeContractVersion": "trusted_node_v2",
+    "timeoutMs": 30000,
+    "sourceFile": {
+      "localPath": "src/functions/qfyy_access_event/index.ts"
+    }
+  },
+  "status": "active"
+}
+```
+
+Webhook Function 的 `timeoutMs` 必须在 1 到 120000 毫秒之间。平台在配置和
+每次调用时都会重新校验运行时契约，Function 后续被禁用、降级为旧运行时或把
+超时调到上限之外时，Webhook 会返回可重试的非 2xx，而不会以宽权限身份执行。
+
+Secret 值只通过隐藏输入或标准输入写入平台：
+
+```bash
+openxiangda secret create yuquan_webhook_secret \
+  --value-stdin --change <change-id> --profile <name>
+```
+
+禁止把值写进 Webhook/Function Manifest、源码、`.env`、日志、异常或函数返回值。
+
+## Function 输入
+
+Function 的第二个参数和 `ctx.input` 都是以下对象：
+
+```ts
+interface WebhookInput {
+  deliveryId: string;
+  idempotencyKey: string;
+  webhookCode: string;
+  receivedAt: string;
+  rawBody: string;
+  rawBodyBase64: string;
+  rawQueryString: string;
+  query: Record<string, string[]>;
+  headers: Record<string, string[]>;
+  body: unknown;
+  request: { method: "POST"; path: string };
+}
+```
+
+`query` 保留重复参数及其顺序。`rawBody` 是签名使用的原始 UTF-8 文本；
+`body` 只用于验签成功后的业务解析。平台会从 `headers` 中移除 Authorization、
+Cookie、代理凭据和客户端证书头。
+
+## 验签顺序
+
+验签、时间窗和事件来源检查必须发生在任何 `ctx.form`、`ctx.dataView`、
+`ctx.connector`、`ctx.notification`、`ctx.platform` 或 `ctx.utils.http` 调用之前。
+永远不要对 `input.body` 再 `JSON.stringify` 后验签，空格、字段顺序或转义变化会
+使签名失真。
+
+下面展示 HMAC-SHA1 和常量时间比较。`buildCanonicalText` 只是结构示例；必须按
+供应商正式文档确认字段顺序、分隔符、URL 编码和 hex/base64 输出格式：
+
+```ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { AppFunctionContextV2 } from "openxiangda/runtime";
+
+type WebhookInput = {
+  deliveryId: string;
+  idempotencyKey: string;
+  rawBody: string;
+  query: Record<string, string[]>;
+  body: unknown;
+};
+
+function first(query: Record<string, string[]>, name: string) {
+  return String(query[name]?.[0] || "");
+}
+
+function equalEncodedSignature(actual: string, expected: string) {
+  const left = Buffer.from(actual.trim().toLowerCase(), "utf8");
+  const right = Buffer.from(expected.trim().toLowerCase(), "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function buildCanonicalText(input: WebhookInput) {
+  // Replace this illustrative order with the provider's exact contract.
+  return [
+    first(input.query, "nonce"),
+    first(input.query, "timestamp"),
+    first(input.query, "orgId"),
+    input.rawBody,
+  ].join("");
+}
+
+export default async function handleWebhook(
+  ctx: AppFunctionContextV2,
+  input: WebhookInput,
+) {
+  const secret = await ctx.secrets.get("yuquan_webhook_secret");
+  const expected = createHmac("sha1", secret)
+    .update(buildCanonicalText(input), "utf8")
+    .digest("hex");
+  const actual = first(input.query, "signature");
+  if (!actual || !equalEncodedSignature(actual, expected)) {
+    return { webhook: { outcome: "rejected", status: 401 } };
+  }
+
+  const timestamp = Number(first(input.query, "timestamp"));
+  if (!Number.isFinite(timestamp) || Math.abs(Date.now() - timestamp) > 5 * 60_000) {
+    return { webhook: { outcome: "rejected", status: 401 } };
+  }
+
+  const event = input.body as {
+    callbackTag?: string;
+    data?: {
+      isAuth?: boolean;
+      deviceSn?: string;
+      jobNum?: string;
+      recognizeTime?: string;
+      recognizeType?: number;
+      memberId?: string;
+      personType?: number;
+    };
+  };
+  if (event.callbackTag !== "REC_SUCCESS" || event.data?.isAuth !== true) {
+    return { webhook: { outcome: "ignored" } };
+  }
+
+  // The application must atomically claim input.idempotencyKey in its own
+  // business record before creating/updating reservation data.
+  await processAccessEventIdempotently(ctx, input.idempotencyKey, event.data);
+  return { webhook: { outcome: "accepted" } };
+}
+```
+
+`processAccessEventIdempotently` 是应用函数中的业务实现，不是平台内置 API。应把
+`idempotencyKey` 写入带唯一约束或等价原子保护的业务记录，然后再执行副作用。
+平台提供 at-least-once 投递；如果 Function 已产生副作用，但进程在成功回执落库前
+中断，同一事件会再次执行。
+
+## 返回契约
+
+- 普通返回，或 `{ webhook: { outcome: "accepted" } }`：HTTP 200。
+- `{ webhook: { outcome: "ignored" } }`：HTTP 200，适合已验签但无需处理的事件。
+- `{ webhook: { outcome: "rejected", status: 400|401|403|409|422 } }`：指定 4xx。
+- `{ webhook: { outcome: "retry" } }` 或抛出异常：HTTP 503，通知供应商重试。
+
+平台不会把 Function 返回值、日志、异常详情或 Secret 回显给外部调用方。
+投递原始请求和审计信息默认保留 180 天，由平台部署环境统一配置；应用不应把
+Webhook 投递表当作永久业务档案，需要长期保存的字段应在验签后写入自己的表单。
+
+## 校验、发布和诊断
+
+```bash
+openxiangda resource validate webhook --profile <name>
+openxiangda resource plan webhook --only yuquan_access --profile <name> --json
+openxiangda resource publish webhook --only yuquan_access \
+  --change <change-id> --profile <name>
+
+openxiangda webhook list --profile <name> --json
+openxiangda webhook get yuquan_access --profile <name> --json
+openxiangda webhook deliveries yuquan_access --profile <name> --json
+openxiangda webhook delivery yuquan_access <delivery-id> --profile <name> --json
+openxiangda webhook disable yuquan_access \
+  --change <change-id> --profile <name>
+```
+
+先发布并验证 Function，再启用 Webhook。新 Function 与 Webhook 同轮交付时，可以
+先以 `status: "disabled"` 发布 Webhook，验证 Function 后再把状态改为 `active`。

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

@@ -157,7 +157,7 @@ An environment-managed release may intentionally replace complete Function/Autom
 
 For an audited Runtime source rollback, managed `release ship`, recovery `release deploy`, and `release promote` accept `--allow-runtime-rollback --reason "..."` with a reason of at least 8 characters. This pair is scoped only to `runtime-stage` and never reaches resource stages or `app-finalize`. Ship freezes it in `ship.json`; production confirmation inherits it automatically. The default remains fail closed.
 
-`release publish` is the normal whole-app entrypoint for legacy unmanaged workspaces: it verifies SDD without mutating reviewed files, waits for the promotion lease, freezes one App capture, stages the exact Form/Backend/Runtime children, resumes from a private execution journal, finalizes once, and releases the lease. For an approved historical-lineage catch-up, add `--adopt-online-baseline --adoption-reason "..."`; the pair reaches only exact `resource publish --only/--code` stages, never Form ensure, Runtime, or App finalize, and invalid or empty scopes fail before lease acquisition. Managed applications use two-phase `release ship` and its deployment-scoped journal. Individual candidate/deploy/test/fail/promote commands are recovery/diagnostic primitives. `release fail --deployment <id> --message <text> [--code <code>] [--details-json <JSON|file>] --environment preproduction` records an audited UAT failure only after verifying the deployment belongs to the selected preproduction environment; production targets and mismatched deployment identities fail before the write.
+`release publish` is the normal whole-app entrypoint for legacy unmanaged workspaces: it verifies SDD without mutating reviewed files, waits for the promotion lease, freezes one App capture, stages the exact Form/Backend/Page children, resumes from a private execution journal, finalizes once, and releases the lease. A legacy Page step runs with `OPENXIANGDA_PAGE_STAGE_ONLY=1`; its environment and staged kind are part of the plan hash, and missing PageRelease evidence blocks Root finalize. Custom page publishers must honor that environment and invoke the current package CLI. For an approved historical-lineage catch-up, add `--adopt-online-baseline --adoption-reason "..."`; the pair reaches only exact `resource publish --only/--code` stages, never Form ensure, Page, or App finalize. A deliberate Backend manifest replacement may add `--replace-manifest --reason "..."`; the pair reaches only the unique exact Backend stage. Invalid reasons or empty/incompatible scopes fail before lease acquisition. Managed applications use two-phase `release ship` and its deployment-scoped journal. Individual candidate/deploy/test/fail/promote commands are recovery/diagnostic primitives. `release fail --deployment <id> --message <text> [--code <code>] [--details-json <JSON|file>] --environment preproduction` records an audited UAT failure only after verifying the deployment belongs to the selected preproduction environment; production targets and mismatched deployment identities fail before the write.
 
 Reviewed bundle commands may retain `<profile>` as a template. The explicit real `release publish --profile <name>` value is bound to actual child argv without rewriting tracked SDD. React SPA page codes remain logical coverage targets and activate through the single Runtime child; they do not require PageRelease. If local lease state disappears, `release end --change <id>` reconciles a self-owned remote lease from the private execution journal and never reports inactive while a remote lease is active.
 

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

@@ -44,7 +44,7 @@ openxiangda workspace publish --profile <name> --page <pageCode>
 - ❌ Raw native form controls in AI-authored page code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers/uploaders). Use platform components or `antd` / `antd-mobile`.
 - ❌ Embed a single `FormProvider` field component temporarily; navigate to a full standard form page or render a complete `StandardFormPage` instead.
 - ❌ Reuse one form UI for both PC and mobile without verifying overlay / picker / bottom-sheet behavior on both viewports.
-- ❌ Hardcode notification or platform API URLs; use `openxiangda/runtime` and `src/resources/notifications/` declarations.
+- ❌ Send notifications directly from a page or hardcode notification/platform API URLs. Pages invoke a named App Function with business identifiers; trusted runtime code uses `ctx.notification` and `src/resources/notifications/` declarations.
 
 ## CLI Flow
 
@@ -133,7 +133,7 @@ Read these references only when editing page code:
 - Store live `pageId`, `routeKey`, and `legacyFormUuid` under the current profile only.
 - Use `openxiangda/runtime` for platform data access instead of hardcoding backend URLs in page code.
 - 家校关系必须通过 `sdk.organization.schoolContact` / `ctx.organization.schoolContact` 读取；班主任班级使用 `teachers.list` 的 `isHeadTeacher`，不要用全局角色推断具体班级，也不要直连钉钉、查询系统表或用同班成员推断亲属关系。
-- For reminders, alerts, and business messages, declare `src/resources/notifications/` first and call `sdk.notification`; do not hardcode notification API URLs.
+- For reminders, alerts, and business messages, declare `src/resources/notifications/` first. Pages call a named App Function through `sdk.function.invoke`; the function authorizes the business action, derives recipients and variables, and sends through trusted `ctx.notification`. Do not hardcode notification API URLs or pass effective recipients/content/channels from the page.
 - For backend business logic shared by pages, automations, or workflows, declare an App Function and call `sdk.function.invoke`; do not duplicate the same multi-form query/connector/notification orchestration in page code.
 - Before hand-writing mature UI behavior, consult `references/component-guide.md` and use established libraries: platform components for platform data fields, antd/antd-mobile for controls and overlays, ECharts for charts, GSAP for complex animation timelines, and maintained packages such as dnd-kit for drag/drop. Do not rebuild mature controls with raw DOM/native inputs.
 - Named imports from `@ant-design/icons` are supported by the `openxiangda` workspace build proxy, which enumerates icon module exports at runtime.

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

@@ -105,6 +105,8 @@ JS_CODE is the backend execution escape hatch for workflow and automation. Use i
 
 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 inbound third-party callbacks, declare `src/resources/webhooks/<code>.json` with a fixed `targetFunctionCode`; do not expose `appType` as a public routing identifier and do not put provider verification fields or Secret values in the Webhook manifest. The Function must use `input.rawBody` for signature verification before any data/helper/network call, read only top-level declared `secretRefs`, and use `input.idempotencyKey` to protect business writes because delivery is at-least-once. Read `references/webhooks.md` for the complete envelope, HMAC example, response directives, publish commands, and delivery diagnosis.
+
 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`.
 
 For new AI-authored automations, prefer code-first `automation_code_ts` resources instead of visual v3 graph definitions. Put the source in `src/automations/<resourceCode>/index.ts`, define `definition.code.json` with `kind: "automation_code_ts"`, and provide `preview.json` for read-only frontend display. Use `ctx.logger.debug/info/warn/error(message, data?)` at every important step; OpenXiangda can inspect logs with `automation executions`, `automation logs`, and `automation diagnose`.
@@ -199,3 +201,4 @@ Use `automation disable` before risky edits. Published automations create a draf
 - Notification resources and runtime calls: `references/notifications.md`
 - API fields: `references/openxiangda-api.md`
 - Profile-isolated IDs: `references/workspace-state.md`
+- Inbound Webhook declaration, verification, idempotency, and delivery diagnosis: `references/webhooks.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.269",
+  "version": "1.0.271",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -68,7 +68,7 @@
     "source:admin-list": "node scripts/sync-admin-list-source.mjs",
     "check": "node --check bin/openxiangda.js && node --check lib/*.js && node --check packages/sdk/src/build-source/src/cli.mjs && node --check packages/sdk/src/build-source/scripts/*.mjs && node --check packages/sdk/src/build-source/scripts/utils/*.mjs",
     "test": "npm run test:fast",
-    "test:fast": "npm run check && node scripts/delivery-v2-package-smoke.mjs && node scripts/delivery-v2-executor-smoke.mjs && node scripts/delivery-v2-release-conformance-smoke.mjs && node scripts/http-proxy-smoke.mjs && node scripts/form-export-cli-smoke.mjs && node scripts/open-api-cli-smoke.mjs && node scripts/release-plan-smoke.mjs && node scripts/typed-resource-plan-smoke.mjs && node scripts/integration-bundle-smoke.mjs && node scripts/content-cache-smoke.mjs && node scripts/dependency-capsule-smoke.mjs && node scripts/sdd-stages-smoke.mjs && node scripts/environment-swap-cli-smoke.mjs && node scripts/environment-policy-cli-smoke.mjs",
+    "test:fast": "npm run check && node scripts/delivery-v2-package-smoke.mjs && node scripts/delivery-v2-executor-smoke.mjs && node scripts/delivery-v2-release-conformance-smoke.mjs && node scripts/http-proxy-smoke.mjs && node scripts/form-export-cli-smoke.mjs && node scripts/open-api-cli-smoke.mjs && node scripts/release-plan-smoke.mjs && node scripts/typed-resource-plan-smoke.mjs && node scripts/webhook-resource-cli-smoke.mjs && node scripts/integration-bundle-smoke.mjs && node scripts/content-cache-smoke.mjs && node scripts/dependency-capsule-smoke.mjs && node scripts/sdd-stages-smoke.mjs && node scripts/environment-swap-cli-smoke.mjs && node scripts/environment-policy-cli-smoke.mjs",
     "test:changed": "npm run check && node scripts/run-test-suite.mjs --changed --evidence",
     "test:contract": "npm run check && node scripts/run-test-suite.mjs --contract --evidence",
     "test:release": "npm run check && node scripts/run-test-suite.mjs --release --evidence",
@@ -80,6 +80,7 @@
     "test:content-cache": "node scripts/content-cache-smoke.mjs",
     "test:dependency-capsule": "node scripts/dependency-capsule-smoke.mjs",
     "test:typed-resource-plan": "node scripts/typed-resource-plan-smoke.mjs",
+    "test:webhook-resource": "node scripts/webhook-resource-cli-smoke.mjs",
     "test:integration-bundle": "node scripts/integration-bundle-smoke.mjs",
     "prepublishOnly": "npm run release:evidence:verify && node scripts/release-mainline-guard.mjs",
     "prepack": "npm run source:admin-list && npm run build:sdk",
@@ -232,42 +233,42 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "1.0.269",
-    "title": "OpenXiangda V1 工作区登录与 V2 升级建议",
+    "version": "1.0.271",
+    "title": "OpenXiangda V1 Legacy Atomic Mixed Releases",
     "status": "reviewed",
-    "summary": "V1 平台登录态按工作区隔离，停止读取和合并全局 profiles；版本、升级与技能刷新入口展示 V2 采用建议。",
-    "newFeatures": [
-      "V1 人类可读命令展示 V2 推荐与迁移评估入口，JSON 结果提供结构化 migrationAdvice。",
-      "login、auth 和 platform 支持 --cwd 指定登录态所属工作区。"
-    ],
+    "summary": "Legacy PageRelease 应用现在可以在一次受审发布中同时暂存 FormRelease、BackendRelease 和 PageRelease，并通过一个 Root AppRelease 原子激活。",
+    "newFeatures": [],
     "fixes": [
-      "登录、刷新与退出读写工作区 .openxiangda/profiles.json，避免不同项目覆盖同一全局账号。",
-      "会话对象固定来源文件，切换目录后仍写回原工作区；登录文件原子保存、权限 0600 并自动忽略 Git 跟踪。",
-      "新建工作区可保留受管登录文件；Git 基线只读检查使用隔离的工作区凭据副本。"
+      "Legacy 发布计划不再把 Form 交给 workspace publish 直接处理，而是生成独立的不可变 FormRelease stage。",
+      "BackendRelease 在依赖的 staged Form contract 就绪后执行，legacy Page 继续使用 PageRelease，最后只执行一次 app-finalize。",
+      "SDD bundle 和 prepublish 校验对 legacy Form、Backend、Page 混合发布使用同一组确定性命令。",
+      "Legacy Page step 自动注入 stage-only 环境并记录 PageRelease staged evidence；缺少证据时禁止 Root finalize。",
+      "Legacy release publish 的 manifest replacement 权限只透传给唯一的精确 Backend stage。"
     ],
     "affectedUsers": [
-      "维护 V1 应用、在多个工作区使用不同平台或账号的开发者。"
+      "使用 legacy PageRelease 且同一变更同时包含 Form、Function/Automation 或 Page 的 OpenXiangda V1 应用。"
     ],
     "compatibility": {
       "node": ">=18；全局 V2 统一入口需要 >=24",
       "workspaceGenerations": [
         "v1"
       ],
-      "workspacePolicy": "原全局 profiles 保留但不再读取，升级后每个项目必须重新登录；已有工作区 profiles 可直接使用。",
-      "platformPolicy": "不改变平台身份、授权协议或生产应用。OSS 环境配置仍由原全局 .env 管理。"
+      "workspacePolicy": "React SPA 发布计划保持兼容；legacy 混合发布会改用 FormRelease + PageRelease + Root AppRelease 的原子编排。",
+      "platformPolicy": "目标平台需已支持 FormRelease、PageRelease、BackendRelease 和 atomic staged children；无需数据库迁移。"
     },
     "upgradeSteps": [
-      "将项目依赖锁定到 openxiangda@1.0.269 或运行同代 update install。",
-      "进入项目重新运行 openxiangda login <platform-url>；新项目先用 --cwd <directory> 指定目标目录登录。",
-      "执行 skill install --force 和 skill bootstrap --force 刷新技能与工作区指引，再运行项目检查。",
-      "使用 Node.js 24 的统一入口查看 V2 迁移建议并执行 migrate assess，按评估结果规划应用迁移。"
+      "将 V1 项目依赖锁定到 openxiangda@1.0.271 或运行同代 update install。",
+      "对待发布变更重新生成 mainline release bundle，或至少重新执行 sdd verify --changed --stage prepublish。",
+      "确认 legacy 计划中的 workspace publish 只包含 pages/*，Form 使用 resource publish form-setting 单独暂存。",
+      "自定义 legacy 页面发布脚本必须遵守 OPENXIANGDA_PAGE_STAGE_ONLY=1，并通过当前包内 CLI 登记 staged PageRelease。",
+      "继续通过 release publish 执行一次性 Root finalize，不要顺序激活 Form、Backend 或 Page。"
     ],
     "knownLimitations": [
-      "不会自动复制全局或其他项目的令牌，也不会自动迁移 V1 应用到 V2。",
-      "同一工作区并发登录或刷新仍受平台令牌有效性约束。"
+      "1.0.270 生成的错误计划不会被原地信任；必须使用 1.0.271 重新计算并通过 SDD gate。",
+      "该补丁不改变网络链路；独立的 ECONNRESET 仍需按请求时间和 ingress 日志排查。"
     ],
     "issues": [],
-    "sha256": "112d003eb255dbdf9b221e6ec16c19fefe4a6e164bff22854e6128ad62df5d01",
-    "url": "https://github.com/1377385356/openxiangda-v1/releases/tag/v1.0.269"
+    "sha256": "86b676d7d8382b8618aad501cd8cf576d95ee0a6c29b8435b9b2edc22b43eee9",
+    "url": "https://github.com/1377385356/openxiangda-v1/releases/tag/v1.0.271"
   }
 }