openxiangda-devkit-core 2.0.0-alpha.29 → 2.0.0-alpha.34

package/dist/application-services.js

@@ -2,10 +2,11 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { SCHEMA_VERSIONS, canonicalJson, } from "openxiangda-contracts";
-import { compileApplicationSources, compileAppPackage, sha256Bytes, validateAppConfig, } from "openxiangda-compiler";
-import { OpenXiangdaControlPlaneClient, } from "./control-plane-client.js";
+import { compileApplicationSources, compileAppPackage, requiredPlatformCapabilities, sha256Bytes, validateAppConfig, } from "./compiler/index.js";
+import { OpenXiangdaControlPlaneClient, ControlPlaneError, } from "./control-plane-client.js";
 import { normalizePlatformBaseUrl, OpenXiangdaDeveloperSession, } from "./session.js";
-import { localDevelopmentStatus, localDevelopmentSession, resetLocalDevelopmentData, runLocalDevelopment, stopLocalDevelopment, } from "./local-development.js";
+import { runConnectedDevelopment, selectConnectedDevelopmentEnvironment, } from "./connected-development.js";
+import { backendImageBuildTarget, publishBackendImage, } from "./backend-image-build.js";
 import { OPENXIANGDA_TOOLCHAIN_VERSION } from "./version.js";
 import { git, loadWorkspace, } from "./workspace-loader.js";
 export class OpenXiangdaApplicationServices {
@@ -289,27 +290,6 @@ export class OpenXiangdaApplicationServices {
         const data = await (await this.client(workspace.root)).setTimerSubscriptionStatus(workspace.config.app.code, timerId, input);
         return this.ok("event.timer.status", workspace.context.workspace, data);
     }
-    async fireLocalTimer(root, timerId) {
-        const workspace = await this.workspace(root);
-        const session = localDevelopmentSession(workspace.root);
-        if (!session || session.status !== "ready" || session.uiOnly) {
-            throw new Error("OPENXIANGDA_LOCAL_DEV_SESSION_REQUIRED");
-        }
-        const response = await fetch(`${session.urls.platform}/__openxiangda-local/timers/${encodeURIComponent(timerId)}/fire`, {
-            method: "POST",
-            headers: {
-                Accept: "application/json",
-                "X-OpenXiangda-Local-Control": "v1",
-            },
-        });
-        const envelope = (await response.json());
-        if (!response.ok || Number(envelope.code) >= 400) {
-            throw new Error(String(envelope.errorCode ||
-                envelope.message ||
-                `OPENXIANGDA_LOCAL_TIMER_FIRE_FAILED:${response.status}`));
-        }
-        return this.ok("event.timer.fire-local", workspace.context.workspace, envelope.data);
-    }
     async workflowAssigneeProviders(root, environmentKey) {
         const workspace = await this.workspace(root);
         const environment = this.deploymentEnvironment(environmentKey);
@@ -347,7 +327,7 @@ export class OpenXiangdaApplicationServices {
         const changed = current !== sources.contracts.typescript;
         const diagnostics = [];
         if (input.check && changed) {
-            diagnostics.push(this.diagnostic("GENERATED_CONTRACTS_OUTDATED", "生成契约与应用声明不一致", relative(workspace.root, output), "运行 openxiangda generate 并提交生成结果"));
+            diagnostics.push(this.diagnostic("GENERATED_CONTRACTS_OUTDATED", "生成契约与应用声明不一致", relative(workspace.root, output), "运行 openxiangda check 并提交生成结果"));
         }
         else if (changed) {
             mkdirSync(dirname(output), { recursive: true });
@@ -362,7 +342,7 @@ export class OpenXiangdaApplicationServices {
                 {
                     code: "generate",
                     label: "更新生成契约",
-                    command: "openxiangda generate",
+                    command: "openxiangda check",
                 },
             ]
             : []);
@@ -373,16 +353,17 @@ export class OpenXiangdaApplicationServices {
             ...validateAppConfig(workspace.config),
             ...this.versionTrainDiagnostics(workspace),
         ];
-        const generated = await this.generate({
-            root: workspace.root,
-            check: true,
-        });
+        const generated = await this.generate({ root: workspace.root });
         diagnostics.push(...generated.diagnostics);
-        const command = this.runPackageScript(workspace.root, "check");
-        if (!command.ok) {
-            diagnostics.push(this.diagnostic("WORKSPACE_CHECK_FAILED", "工作区 check 脚本失败", "package.json#scripts.check", "修复类型、契约或静态检查错误后重试", { output: command.output }));
+        const stages = ["check", "test", "build"].map(name => ({
+            name,
+            ...this.runPackageScript(workspace.root, name),
+        }));
+        for (const stage of stages.filter(item => !item.ok)) {
+            const code = `WORKSPACE_${stage.name.toUpperCase()}_FAILED`;
+            diagnostics.push(this.diagnostic(code, `工作区 ${stage.name} 脚本失败`, `package.json#scripts.${stage.name}`, "修复失败后重新运行 openxiangda check", { output: stage.output }));
         }
-        return this.result("check", workspace.context.workspace, { stages: [{ name: "workspace", ...command }] }, diagnostics);
+        return this.result("check", workspace.context.workspace, { generated: generated.data, stages }, diagnostics);
     }
     async test(root) {
         const workspace = await this.workspace(root);
@@ -408,6 +389,18 @@ export class OpenXiangdaApplicationServices {
             },
         };
     }
+    async buildPreview(root) {
+        const checked = await this.check(root);
+        return {
+            ...checked,
+            operation: "build.preview",
+            data: {
+                sealed: false,
+                packageDigest: null,
+                check: checked.data,
+            },
+        };
+    }
     async buildSealed(input = {}) {
         const workspace = await this.workspace(input.root);
         const diagnostics = [];
@@ -419,13 +412,13 @@ export class OpenXiangdaApplicationServices {
                 return this.result("build", workspace.context.workspace, undefined, diagnostics);
             }
         }
-        const backendImage = String(input.backendImage || process.env.OPENXIANGDA_BACKEND_IMAGE || "").trim();
+        const backendImage = String(input.backendImage || "").trim();
         if (!backendImage) {
-            diagnostics.push(this.diagnostic("BACKEND_IMAGE_REQUIRED", "当前应用包含 NestJS 后端，密封 AppPackage 时必须提供不可变 OCI image", "backend.image", "通过 --backend-image <registry/repository@sha256:digest> 或 OPENXIANGDA_BACKEND_IMAGE 提供"));
+            diagnostics.push(this.diagnostic("BACKEND_IMAGE_REQUIRED", "当前应用包含 NestJS 后端，密封 AppPackage 时必须提供不可变 OCI image", "backend.image", "运行 openxiangda deploy 由工具自动构建并推送官方后端镜像"));
             return this.result("build", workspace.context.workspace, undefined, diagnostics);
         }
         if (!/@sha256:[a-f0-9]{64}$/i.test(backendImage)) {
-            diagnostics.push(this.diagnostic("BACKEND_IMAGE_NOT_IMMUTABLE", "后端镜像必须使用不可变 sha256 digest，不能使用可变 tag", "backend.image", "将镜像引用改为 <registry/repository@sha256:64位摘要>"));
+            diagnostics.push(this.diagnostic("BACKEND_IMAGE_NOT_IMMUTABLE", "后端镜像必须使用不可变 sha256 digest，不能使用可变 tag", "backend.image", "运行 openxiangda deploy 重新构建并取得不可变镜像摘要"));
             return this.result("build", workspace.context.workspace, undefined, diagnostics);
         }
         const sources = compileApplicationSources(workspace.config, this.toolchainVersion);
@@ -502,39 +495,63 @@ export class OpenXiangdaApplicationServices {
             {
                 code: "deploy",
                 label: "部署到预发",
-                command: "openxiangda deploy preproduction",
+                command: "openxiangda deploy",
             },
         ]);
     }
     async deploymentPlan(input) {
-        const built = await this.build({ ...input, write: false });
-        if (!built.ok || !built.data)
-            return built;
-        return {
-            ...built,
-            operation: "deployment.plan",
-            data: {
-                environment: input.environment,
-                packageDigest: built.data.package.digest,
-                appCode: built.data.package.manifest.appCode,
-                artifacts: built.data.package.manifest.artifacts,
-                requiredCapabilities: built.data.package.manifest.compatibility.requiredCapabilities,
-            },
-        };
+        const workspace = await this.workspace(input.root);
+        const sources = compileApplicationSources(workspace.config, this.toolchainVersion);
+        return this.ok("deployment.plan", workspace.context.workspace, {
+            environment: input.environment,
+            appCode: workspace.config.app.code,
+            sealed: false,
+            packageDigest: null,
+            buildOwner: "openxiangda deploy",
+            frontendRoot: workspace.config.frontend.root,
+            backendRoot: workspace.config.backend.root,
+            configDigest: sources.config.digest,
+            contractDigest: sources.contracts.digest,
+        });
     }
     async deploy(input) {
         const workspace = await this.workspace(input.root);
         if (String(input.environment) !== "preproduction") {
             return this.result("deploy", workspace.context.workspace, undefined, [
-                this.diagnostic("DEPLOY_PREPRODUCTION_ONLY", "Native 2.0 只允许直接部署到预发环境", String(input.environment), "使用 openxiangda deploy preproduction；生产环境必须晋级同一 AppVersion"),
+                this.diagnostic("DEPLOY_PREPRODUCTION_ONLY", "Native 2.0 只允许直接部署到预发环境", String(input.environment), "使用 openxiangda deploy；生产环境必须显式复用成功的测试 DeploymentRun"),
             ]);
         }
-        const built = await this.buildSealed({ ...input, root: workspace.root });
+        const client = await this.client(workspace.root);
+        const capabilities = await client.capabilities();
+        const { assertRequiredCapabilitiesAvailable } = await import("./deployment.js");
+        assertRequiredCapabilitiesAvailable(capabilities, requiredPlatformCapabilities(workspace.config));
+        const target = input.backendImage
+            ? undefined
+            : backendImageBuildTarget(capabilities, workspace.config.app.code);
+        const checked = await this.check(workspace.root);
+        if (!checked.ok)
+            return { ...checked, operation: "deploy" };
+        const backendImage = input.backendImage
+            ? input.backendImage
+            : (await publishBackendImage({
+                root: workspace.root,
+                backendRoot: workspace.config.backend.root,
+                target: target,
+                ...(workspace.context.workspace.revision
+                    ? { sourceRevision: workspace.context.workspace.revision }
+                    : {}),
+            })).reference;
+        const built = await this.buildSealed({
+            ...input,
+            root: workspace.root,
+            backendImage,
+            skipWorkspaceBuild: true,
+        });
         if (!built.ok || !built.data)
             return built;
-        const client = await this.client(workspace.root);
         const deployment = await (await import("./deployment.js")).submitAppPackage({
             client,
+            capabilities,
             compiledPackage: built.data.package,
             artifactContent: built.data.artifactContent,
             environmentKind: input.environment,
@@ -556,7 +573,14 @@ export class OpenXiangdaApplicationServices {
         const client = await this.client(workspace.root);
         const data = deploymentId
             ? await client.deployment(workspace.config.app.code, deploymentId)
-            : await client.deployments(workspace.config.app.code, 20);
+            : (await client.deployments(workspace.config.app.code, 1)).items[0];
+        if (!data) {
+            return this.result("status", workspace.context.workspace, undefined, [
+                this.diagnostic("DEPLOYMENT_NOT_FOUND", "当前应用还没有部署记录", "deploymentId", "运行 openxiangda deploy 创建测试部署"),
+            ], [
+                { code: "deploy", label: "部署测试环境", command: "openxiangda deploy" },
+            ]);
+        }
         return this.ok("status", workspace.context.workspace, data);
     }
     async environmentStatus(root) {
@@ -572,12 +596,14 @@ export class OpenXiangdaApplicationServices {
     }
     async deploymentLogs(root, deploymentId) {
         const status = await this.deploymentStatus(root, deploymentId);
+        if (!status.ok || !status.data)
+            return { ...status, operation: "logs" };
         const run = status.data;
         return {
             ...status,
             operation: "logs",
             data: {
-                deploymentId,
+                deploymentId: run.id,
                 status: run.status,
                 stage: run.stage,
                 checkpoints: run.checkpoints,
@@ -596,11 +622,9 @@ export class OpenXiangdaApplicationServices {
         const deployment = await (await this.client(workspace.root)).cancelDeployment(workspace.config.app.code, deploymentId);
         return this.ok("cancel", workspace.context.workspace, deployment);
     }
-    async promote(root, deploymentId, environment) {
+    async deployProduction(root, deploymentId) {
         const workspace = await this.workspace(root);
-        if (String(environment) !== "production") {
-            throw new Error(`OPENXIANGDA_PROMOTION_ENVIRONMENT_INVALID: ${String(environment)}`);
-        }
+        const environment = "production";
         const client = await this.client(workspace.root);
         const source = await client.deployment(workspace.config.app.code, deploymentId);
         const appVersionId = String(source.result?.applicationVersionId || "");
@@ -608,7 +632,7 @@ export class OpenXiangdaApplicationServices {
             throw new Error("DEPLOYMENT_APP_VERSION_NOT_AVAILABLE");
         const diagnostics = await this.productionPromotionDiagnostics(workspace, client, source, appVersionId);
         if (diagnostics.length > 0) {
-            return this.result("promote", workspace.context.workspace, undefined, diagnostics);
+            return this.result("deploy", workspace.context.workspace, undefined, diagnostics);
         }
         const deployment = await client.promote({
             appCode: workspace.config.app.code,
@@ -616,7 +640,9 @@ export class OpenXiangdaApplicationServices {
             environmentKind: environment,
             idempotencyKey: `promote:${source.packageDigest}:${environment}`,
         });
-        return this.ok("promote", workspace.context.workspace, deployment);
+        return this.ok("deploy", workspace.context.workspace, deployment, [
+            { code: "status", label: "查看生产部署状态", command: `openxiangda status ${deployment.id}` },
+        ]);
     }
     async productionPromotionDiagnostics(workspace, client, source, appVersionId) {
         const diagnostics = [];
@@ -704,63 +730,10 @@ export class OpenXiangdaApplicationServices {
             {
                 code: "status",
                 label: "查看环境状态",
-                command: "openxiangda environment status",
+                command: "openxiangda status",
             },
         ]);
     }
-    async doctor(root) {
-        const workspace = await this.workspace(root);
-        const commands = ["git", "node", "pnpm", "docker"].map((command) => {
-            const result = spawnSync(command, ["--version"], { encoding: "utf8" });
-            return {
-                command,
-                ok: result.status === 0,
-                version: String(result.stdout || result.stderr || "").trim(),
-            };
-        });
-        const dockerInfo = spawnSync("docker", ["info", "--format", "{{.ServerVersion}}"], { encoding: "utf8" });
-        const containerRuntime = {
-            requiredFor: "openxiangda dev",
-            ok: dockerInfo.status === 0,
-            serverVersion: String(dockerInfo.stdout || "").trim() || null,
-            message: dockerInfo.status === 0
-                ? null
-                : String(dockerInfo.stderr || dockerInfo.stdout || "").trim() ||
-                    "Docker daemon is unavailable",
-        };
-        let platform;
-        try {
-            platform = (await (await this.client(workspace.root)).capabilities());
-        }
-        catch (error) {
-            platform = { ok: false, message: error.message };
-        }
-        const diagnostics = commands
-            .filter((item) => !item.ok)
-            .map((item) => this.diagnostic("TOOLCHAIN_COMMAND_MISSING", `缺少必需命令: ${item.command}`, item.command));
-        if (!containerRuntime.ok &&
-            commands.find(item => item.command === "docker")?.ok) {
-            diagnostics.push(this.diagnostic("LOCAL_CONTAINER_RUNTIME_UNAVAILABLE", "Docker 已安装但容器运行时不可用，完整本地开发无法启动 PostgreSQL", "docker.info", "启动 Docker Desktop（或兼容 Docker daemon）后重新执行 openxiangda doctor"));
-        }
-        return this.result("doctor", workspace.context.workspace, {
-            commands,
-            containerRuntime,
-            localDevelopment: localDevelopmentStatus(workspace.root),
-            platform,
-        }, diagnostics);
-    }
-    async devStatus(root) {
-        const workspace = await this.workspace(root);
-        return this.ok("dev.status", workspace.context.workspace, localDevelopmentStatus(workspace.root));
-    }
-    async devStop(root) {
-        const workspace = await this.workspace(root);
-        return this.ok("dev.stop", workspace.context.workspace, await stopLocalDevelopment(workspace.root));
-    }
-    async devResetData(root) {
-        const workspace = await this.workspace(root);
-        return this.ok("dev.reset", workspace.context.workspace, await resetLocalDevelopmentData(workspace.root));
-    }
     async dev(root, input = {}) {
         const workspace = await this.workspace(root);
         const generated = await this.generate({
@@ -769,53 +742,101 @@ export class OpenXiangdaApplicationServices {
         if (!generated.ok) {
             return this.result("dev", workspace.context.workspace, undefined, generated.diagnostics, generated.nextActions);
         }
-        const localFixturePath = join(workspace.root, "openxiangda.local.json");
-        let localFixture;
-        if (existsSync(localFixturePath)) {
+        try {
+            const linkPath = join(workspace.root, ".openxiangda", "link.json");
+            if (!existsSync(linkPath)) {
+                throw new Error("OPENXIANGDA_CONNECTED_LINK_REQUIRED: 先运行 openxiangda create <directory>");
+            }
+            let link;
             try {
-                localFixture = JSON.parse(readFileSync(localFixturePath, "utf8"));
+                link = JSON.parse(readFileSync(linkPath, "utf8"));
             }
-            catch (error) {
-                return this.result("dev", workspace.context.workspace, undefined, [
-                    this.diagnostic("LOCAL_DEVELOPMENT_FIXTURE_INVALID", `本地开发夹具不是有效 JSON: ${error.message}`, localFixturePath, "修复 openxiangda.local.json 后重试"),
-                ]);
+            catch {
+                throw new Error("OPENXIANGDA_CONNECTED_LINK_INVALID");
             }
-        }
-        const local = await runLocalDevelopment({
-            root: workspace.root,
-            appCode: workspace.config.app.code,
-            runtimeOAuthScopes: [
-                ...new Set((workspace.config.authz?.roles || []).flatMap(role => role.capabilities || [])),
-            ],
-            eventSubscriptionCodes: (workspace.config.events?.subscriptions || []).map(subscription => subscription.code),
-            localManifest: {
-                schemaVersion: 1,
+            if (link.schemaVersion !== 2 || link.appCode !== workspace.config.app.code || !link.baseUrl) {
+                throw new Error("OPENXIANGDA_CONNECTED_LINK_INVALID");
+            }
+            const developerSession = await OpenXiangdaDeveloperSession.load();
+            if (!developerSession) {
+                throw new Error("OPENXIANGDA_CONNECTED_LOGIN_REQUIRED: 先运行 openxiangda login");
+            }
+            developerSession.assertPlatform(link.baseUrl);
+            await developerSession.whoami();
+            const client = new OpenXiangdaControlPlaneClient({
+                baseUrl: developerSession.baseUrl,
+                tokenProvider: developerSession,
+            });
+            const environments = await client.applicationEnvironments(workspace.config.app.code);
+            const environment = selectConnectedDevelopmentEnvironment(environments.items);
+            if (!environment) {
+                throw new Error("OPENXIANGDA_CONNECTED_ACTIVE_ENVIRONMENT_REQUIRED: 应用需要已发布的 test(preproduction) 或 production 环境");
+            }
+            const sources = compileApplicationSources(workspace.config, this.toolchainVersion);
+            const remoteSession = {
+                create: async () => {
+                    const value = await client.createConnectedDevelopmentSession(workspace.config.app.code, {
+                        environmentKey: environment.environmentKey,
+                        manifestDigest: sources.config.digest,
+                    });
+                    return {
+                        id: value.sessionId,
+                        token: value.sessionToken,
+                        expiresAt: value.expiresAt,
+                        mode: value.mode,
+                        manifestOverlay: value.manifestOverlay,
+                        manifestDigest: value.manifestDigest,
+                    };
+                },
+                current: async (token) => {
+                    const value = await client.connectedDevelopmentSession(workspace.config.app.code, token);
+                    return {
+                        id: value.sessionId,
+                        expiresAt: value.expiresAt,
+                        mode: value.mode,
+                        manifestOverlay: value.manifestOverlay,
+                        manifestDigest: value.manifestDigest,
+                    };
+                },
+                refresh: async (token) => {
+                    const value = await client.refreshConnectedDevelopmentSession(workspace.config.app.code, token);
+                    return {
+                        id: value.sessionId,
+                        expiresAt: value.expiresAt,
+                        mode: value.mode,
+                        manifestOverlay: value.manifestOverlay,
+                        manifestDigest: value.manifestDigest,
+                    };
+                },
+                revoke: async (token) => {
+                    await client.revokeConnectedDevelopmentSession(workspace.config.app.code, token);
+                },
+            };
+            input.onStatus?.("首版 connected dev 使用已发布资源；检测到未发布字段时请先部署 test");
+            const connected = await runConnectedDevelopment({
+                root: workspace.root,
                 appCode: workspace.config.app.code,
-                resources: workspace.config.data?.resources || [],
-                roles: workspace.config.authz?.roles || [],
-                scopeDimensions: workspace.config.authz?.scopeDimensions || [],
-                dataPolicies: workspace.config.authz?.dataPolicies || [],
-                backendSecrets: workspace.config.backend?.secrets || [],
-                eventSubscriptions: workspace.config.events?.subscriptions || [],
-                timerSubscriptions: workspace.config.events?.timers || [],
-                workflowDefinitions: workspace.config.workflows?.definitions || [],
-                workflowBindings: workspace.config.workflows?.bindings || [],
-                workflowActivations: workspace.config.workflows?.activations || [],
-                workflowProviders: workspace.config.workflows?.providers || [],
-                ...(localFixture ? { fixture: localFixture } : {}),
-            },
-            ...(input.noOpen === undefined ? {} : { noOpen: input.noOpen }),
-            ...(input.reset === undefined ? {} : { reset: input.reset }),
-            ...(input.uiOnly === undefined ? {} : { uiOnly: input.uiOnly }),
-            ...(input.webPort === undefined ? {} : { webPort: input.webPort }),
-            ...(input.onStatus ? { onStatus: input.onStatus } : {}),
-        });
-        const diagnostics = local.exitCode === 0
-            ? []
-            : [
-                this.diagnostic("DEV_PROCESS_FAILED", "本地开发进程异常退出", local.logPath, "查看本地诊断和日志后重试", { diagnosticsPath: local.diagnosticsPath }),
-            ];
-        return this.result("dev", workspace.context.workspace, local, diagnostics);
+                platformBaseUrl: developerSession.baseUrl,
+                environment,
+                developerSession,
+                remoteSession,
+                ...(input.noOpen === undefined ? {} : { noOpen: input.noOpen }),
+                ...(input.webPort === undefined ? {} : { webPort: input.webPort }),
+                ...(input.onStatus ? { onStatus: input.onStatus } : {}),
+            });
+            const diagnostics = connected.exitCode === 0
+                ? []
+                : [
+                    this.diagnostic("DEV_PROCESS_FAILED", "连接式开发进程异常退出", workspace.root, "查看 Web 或 Nest 进程的终端输出后重试"),
+                ];
+            return this.result("dev", workspace.context.workspace, connected, diagnostics);
+        }
+        catch (error) {
+            const failure = this.connectedDevelopmentFailure(error, workspace.root);
+            return this.result("dev", workspace.context.workspace, undefined, [
+                this.diagnostic(failure.code, failure.message, failure.path, failure.remediation),
+            ], [{ code: failure.actionCode, label: failure.actionLabel, command: failure.command }]);
+        }
     }
     async workspace(root) {
         return await loadWorkspace(root, this.toolchainVersion);
@@ -996,6 +1017,82 @@ export class OpenXiangdaApplicationServices {
             ...(details ? { details } : {}),
         };
     }
+    connectedDevelopmentFailure(error, workspaceRoot) {
+        const rawCode = String(error?.code ||
+            (error instanceof Error ? error.message.split(":", 1)[0] : "") ||
+            "OPENXIANGDA_CONNECTED_DEV_FAILED").trim();
+        const known = {
+            OPENXIANGDA_CONNECTED_LINK_REQUIRED: {
+                message: "当前工作区尚未绑定 OpenXiangda 平台",
+                remediation: "运行 create 幂等完成工作区绑定和平台初始化",
+                actionCode: "create",
+                actionLabel: "初始化应用",
+                command: "openxiangda create <directory>",
+                path: ".openxiangda/link.json",
+            },
+            OPENXIANGDA_CONNECTED_LINK_INVALID: {
+                message: "当前工作区的平台绑定无效或属于另一个应用",
+                remediation: "运行 create 幂等校验并重新生成当前应用绑定",
+                actionCode: "create",
+                actionLabel: "重新初始化应用",
+                command: "openxiangda create <directory>",
+                path: ".openxiangda/link.json",
+            },
+            OPENXIANGDA_CONNECTED_LOGIN_REQUIRED: {
+                message: "尚未登录 OpenXiangda 平台",
+                remediation: "登录工作区绑定的平台后重试",
+                actionCode: "login",
+                actionLabel: "登录平台",
+                command: "openxiangda login --base-url <platform>",
+            },
+            OPENXIANGDA_AUTH_REQUIRED: {
+                message: "OpenXiangda 登录已失效",
+                remediation: "重新登录工作区绑定的平台后重试",
+                actionCode: "login",
+                actionLabel: "重新登录",
+                command: "openxiangda login --base-url <platform>",
+            },
+            OPENXIANGDA_PLATFORM_SESSION_MISMATCH: {
+                message: "工作区绑定平台与当前登录平台不一致",
+                remediation: "切换登录平台，或明确重新绑定当前工作区",
+                actionCode: "login",
+                actionLabel: "切换登录平台",
+                command: "openxiangda login --base-url <linked-platform>",
+                path: ".openxiangda/link.json",
+            },
+            OPENXIANGDA_CONNECTED_ACTIVE_ENVIRONMENT_REQUIRED: {
+                message: "应用没有可用于 connected dev 的已发布环境",
+                remediation: "先发布 test(preproduction)；只有 production 时也可以直接连接正式数据",
+                actionCode: "deploy.test",
+                actionLabel: "部署 test",
+                command: "openxiangda deploy",
+            },
+        };
+        const dataRemediation = error
+            ?.data?.remediation;
+        const remoteRemediation = error instanceof ControlPlaneError
+            ? error.remote?.remediation ||
+                (typeof dataRemediation === "string" ? dataRemediation : undefined)
+            : undefined;
+        const selected = known[rawCode] || {
+            message: "连接式开发预检失败",
+            remediation: remoteRemediation || (error instanceof Error && error.message
+                ? error.message.replace(/Bearer\s+\S+/gi, "Bearer [redacted]")
+                : "检查平台登录、应用权限和 Dev Session 状态后重试"),
+            actionCode: "dev.retry",
+            actionLabel: "重试 connected dev",
+            command: "openxiangda dev",
+        };
+        return {
+            code: rawCode,
+            message: selected.message,
+            remediation: selected.remediation,
+            actionCode: selected.actionCode,
+            actionLabel: selected.actionLabel,
+            command: selected.command,
+            path: selected.path || workspaceRoot,
+        };
+    }
     ok(operation, workspace, data, nextActions = []) {
         return {
             ok: true,