make-app-runtime

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

make-app-runtime

Use this skill for Make App runtime and packaging contracts. These rules are intentionally strict because platform image entrypoints and publish artifacts should not vary per POC.

This skill owns project runtime structure, workspace manifests, build outputs, Service start entry, Service port baseline, runtime config file location, Docker/K8s runtime entry alignment, publish-readiness script guidance, and publish-readiness checks.

It does not own UI layout (

makeui

), authentication implementation (

make-app-auth

), single-app permission logic (

make-app-permission

), Make adapter environment variable semantics (

make-app-service

), DSL modeling (

makedsl

), Make resource deployment (

makecli

), or canvas-table behavior (

canvas-table-integration

本技能用于处理Make App运行时与打包约定。这些规则刻意保持严格，因为平台镜像入口点和发布产物不应因每个POC而有所不同。

本技能负责项目运行时结构、工作区清单、构建产物、Service启动入口、Service端口基线、运行时配置文件位置、Docker/K8s运行时入口对齐、发布就绪脚本指导以及发布就绪检查。

本技能不负责UI布局（

makeui

）、认证实现（

make-app-auth

）、单应用权限逻辑（

make-app-permission

）、Make适配器环境变量语义（

make-app-service

）、DSL建模（

makedsl

）、Make资源部署（

makecli

）或canvas-table行为（

canvas-table-integration

）。

Quick start

快速开始

Identify whether the task touches
```
apps/
```
,
```
apps/service
```
,
```
apps/ui/dist
```
, package scripts, Docker/K8s, image entrypoints, publish readiness, or a runtime error such as
```
Cannot find module '/app/apps/service/dist/server.js'
```
.
Preserve the platform image contract unless the user explicitly says the platform contract itself is changing.
For a new App or an explicit runtime migration, verify the runtime baseline in
```
apps/package.json
```
: it must declare
```
"packageManager": "pnpm@10.20.0"
```
and
```
"engines": { "node": "22.20.0", "pnpm": "10.20.0" }
```
. Existing Make Apps keep their declared runtime during unrelated work; change it only after the user requests an explicit runtime migration.
For a new or explicitly migrated App, run package commands through Corepack (
```
corepack pnpm
```
), not an ambient
```
pnpm
```
binary. For an existing App without a runtime migration, use its compatible declared package manager, lockfile, and established workspace workflow.
For a new or explicitly reorganized App, verify workspace manifests:
```
apps/package.json
```
,
```
apps/pnpm-workspace.yaml
```
,
```
apps/ui/package.json
```
, and
```
apps/service/package.json
```
. For a legacy App, first identify its actual workspace structure without rewriting it.
Verify build artifacts before declaring ready: frontend
```
apps/ui/dist
```
and the Service entry selected by the actual platform image (
```
apps/service/dist/server.js
```
for the default contract).
Add or preserve a contract test for the Service runtime entry.

确认任务是否涉及
```
apps/
```
、
```
apps/service
```
、
```
apps/ui/dist
```
、包脚本、Docker/K8s、镜像入口点、发布就绪，或类似
```
Cannot find module '/app/apps/service/dist/server.js'
```
的运行时错误。
保留平台镜像约定，除非用户明确说明平台约定本身需要变更。
对于新应用或明确的运行时迁移，需验证
```
apps/package.json
```
中的运行时基线：必须声明
```
"packageManager": "pnpm@10.20.0"
```
和
```
"engines": { "node": "22.20.0", "pnpm": "10.20.0" }
```
。现有Make App在非相关工作中应保留其声明的运行时；仅在用户明确请求运行时迁移时才可修改。
对于新应用或已明确迁移的应用，通过Corepack（
```
corepack pnpm
```
）运行包命令，而非环境中的
```
pnpm
```
二进制文件。对于未进行运行时迁移的现有应用，使用其兼容的已声明包管理器、锁文件和既定工作区工作流。
对于新应用或已明确重组的应用，验证工作区清单：
```
apps/package.json
```
、
```
apps/pnpm-workspace.yaml
```
、
```
apps/ui/package.json
```
和
```
apps/service/package.json
```
。对于遗留应用，首先确认其实际工作区结构，不要重写。
在声明就绪前验证构建产物：前端
```
apps/ui/dist
```
以及实际平台镜像选用的Service入口（默认约定下为
```
apps/service/dist/server.js
```
）。
添加或保留针对Service运行时入口的约定测试。

Workspace contract

工作区契约

Newly generated or explicitly runtime-reorganized Make App projects use:

```
apps/ui
```
```
apps/service
```
```
apps/dsl
```
```
apps/docs
```
```
apps/packages/*
```
when shared packages are needed

Required workspace files:

```
apps/package.json
```
```
apps/pnpm-workspace.yaml
```
```
apps/ui/package.json
```
```
apps/service/package.json
```

apps/pnpm-workspace.yaml

must include:

yaml

packages:
  - "ui"
  - "service"
  - "packages/*"

新生成的或已明确进行运行时重组的Make App项目使用以下结构：

```
apps/ui
```
```
apps/service
```
```
apps/dsl
```
```
apps/docs
```
需要共享包时使用
```
apps/packages/*
```

必需的工作区文件：

```
apps/package.json
```
```
apps/pnpm-workspace.yaml
```
```
apps/ui/package.json
```
```
apps/service/package.json
```

apps/pnpm-workspace.yaml

必须包含：

yaml

packages:
  - "ui"
  - "service"
  - "packages/*"

Package manager contract

包管理器契约

All newly generated Make App React workspaces, and existing Apps undergoing an explicit runtime migration, use the fixed runtime triple: Node.js 22.20.0, its bundled Corepack 0.34.0, and pnpm 10.20.0. The workspace root (

apps/package.json

) must declare the exact Node and pnpm versions:

json

{
  "packageManager": "pnpm@10.20.0",
  "engines": {
    "node": "22.20.0",
    "pnpm": "10.20.0"
  }
}

Each executable workspace package, including

apps/ui/package.json

and

apps/service/package.json

, must declare

"engines": { "node": "22.20.0" }

. The project

engines.node

field rejects unsupported runtimes. Do not add

engineStrict

solely for this runtime baseline: it also enforces dependency engine declarations and requires a repository-specific compatibility decision.

The repository must also contain a

.nvmrc

with exactly

22.20.0

, and CI or the Make build image must select exactly Node.js

22.20.0

engines

is a compatibility guard; it does not select the Node binary used by a build environment.

Existing Make Apps retain their declared Node and package-manager versions during UI, auth, filtering, Service, or DSL work. That includes compatible npm and Yarn projects: preserve their existing

package-lock.json

yarn.lock

, workspace install target, and CI workflow. Do not rewrite

packageManager

engines

, lockfiles, or Node-selection files unless the user explicitly requests an explicit runtime migration. Perform that migration in a dedicated change with the project's tests and a Beta deployment. If the manager declaration, lockfile, workspace/CI workflow, or target platform build requirement conflicts, stop and report the compatibility blocker under

make-app-runtime

; do not generate a second lockfile or silently convert the App to pnpm.

For new or explicitly migrated pnpm Apps, enable Corepack before project work and run installation, tests, builds, package additions, and publish gates as

corepack pnpm ...

. Corepack reads the project declaration; a globally installed

pnpm

, including a newer major version, must not be used for these Apps. For an existing compatible pnpm App, use its declared pnpm version through Corepack. For an existing npm or Yarn App without migration, use the repository's established commands and lockfile; do not introduce Corepack or pnpm solely for an unrelated change. Child workspace manifests must not declare a conflicting package-manager version.

For a new or explicitly migrated pnpm App,

apps/package.json

must provide runnable scripts such as

app:ui

app:service

dev

test

, and

build

corepack pnpm --filter

targets must match the actual package names, including scoped names. A legacy App keeps its established equivalent scripts and workspace targets.

make-app-runtime

is the owner of

apps/package.json

generation and repair.

makecli app deploy

must not generate or rewrite workspace manifests.

Treat

makecli app deploy

as a code deployment boundary unless the target makecli version is proven to run a stricter publish gate. Do not report a generated App as publish-ready merely because deploy succeeded.

When preparing a new or explicitly migrated App for publish, provide enough project-local scripts and documentation for the agent or CI to run publish-readiness checks before deploy:

enable Corepack and install dependencies for
```
apps
```
with
```
corepack pnpm install --frozen-lockfile
```
verify Node.js is exactly
```
22.20.0
```
and Corepack is exactly
```
0.34.0
```
run the workspace build
run the
```
make-app-auth
```
published contract audit for Service-fronted Apps
run the
```
make-app-observability
```
Trace audit and behavior tests for every new Make App, whether direct-gateway or Service-fronted
run the
```
make-app-permission
```
contract audit when single-app permission enforcement is enabled or required by a repository-local delivery baseline
run Service gateway-mode contract tests proving local preview and published upstream scopes are separated
verify
```
apps/ui/dist
```
and
```
apps/service/dist/server.js
```
run Service contract tests, including auth callback proxy behavior, when tests exist

For a new or explicitly migrated pnpm Service-fronted App, prefer a project-local

verify:publish

script that runs the publish gate in one command. Keep

check:publish

for build/artifact checks, but do not make it the only release gate. Add

trace:audit

for every new App. When single-app permission enforcement is enabled or locally required, add

permission:audit

to that command; do not make unrelated Apps depend on a missing permission runtime. A legacy App uses its existing release command with the equivalent applicable checks.

Recommended workspace scripts for a new or explicitly migrated pnpm App. Before adding these to

package.json

, copy or wrap the audit utilities into project-local

scripts/

; do not write user-specific skill install paths into generated projects. Do not copy these pnpm-specific scripts into a legacy npm/Yarn App without an explicit runtime migration.

json

{
  "scripts": {
    "check:runtime": "node -e \"if (process.versions.node !== '22.20.0') throw new Error(`Make Apps require Node.js 22.20.0; got ${process.versions.node}`)\" && test \"$(corepack --version)\" = \"0.34.0\"",
    "auth:audit": "node scripts/audit-auth-contract.mjs . --mode service-fronted --published",
    "trace:audit": "node scripts/audit-trace-contract.mjs . --mode service-fronted",
    "schema:diff": "cd .. && makecli diff -f apps/dsl --output=json",
    "check:publish": "corepack pnpm run build && test -f service/dist/server.js && test -d ui/dist",
    "verify:publish": "corepack pnpm run check:runtime && corepack pnpm run test && corepack pnpm run auth:audit && corepack pnpm run trace:audit && corepack pnpm run check:publish && corepack pnpm run schema:diff"
  }
}

For an App with single-app permission enforcement, add

"permission:audit": "node scripts/audit-make-app-permission.mjs ."

and append

&& corepack pnpm run permission:audit

verify:publish

For a direct-gateway App, use

--mode direct

trace:audit

and keep the same default Trace requirement. The Trace contract itself belongs to

make-app-observability

; this Skill only ensures its checks run before deployment.

Do not describe

verify:publish

as a universal makecli hook unless the target makecli version supports it. It is a project-local quality gate to run before

makecli app deploy

Do not pass backend-context flags through

verify:publish

. For a new or explicitly migrated pnpm App, run the gate as

corepack pnpm run verify:publish

; a compatible legacy App uses its established equivalent gate and package manager. Then deploy code to Beta with

makecli app deploy --context <context> --profile <profile> --wait

. Follow the

makecli

skill for the Beta completion guide and, after explicit user authorization, publish that Beta version to Prod with

makecli app promote --context <context> --profile <profile> --yes --wait

. Keep the same backend context/profile throughout; promotion uses the deployed Beta version and does not push local code. If a project-local Node wrapper must accept flags through

corepack pnpm run

, normalize argv by dropping a standalone

--

before parsing because

corepack pnpm run <script> -- --flag

can expose that separator to the script.

For Service-fronted Apps, the Service test suite (run via the project's declared package manager;

corepack pnpm run test

for a new/migrated pnpm App) must include the gateway-mode contract:

MAKE_APP_LOCAL_PREVIEW=true

: Service uses

makecli configure resolve --target local-preview --output=json

field

make_api_origin

and

/api/make/**

published mode, where the flag is absent or false: Service uses the deployed k8s-internal gateway origin and
```
/make/**
```
.
The local-preview token branch is unreachable in published mode.

所有新生成的Make App React工作区，以及正在进行明确运行时迁移的现有应用，均使用固定的运行时三件套：Node.js 22.20.0、其捆绑的Corepack 0.34.0以及pnpm 10.20.0。工作区根目录（

apps/package.json

）必须声明确切的Node和pnpm版本：

json

{
  "packageManager": "pnpm@10.20.0",
  "engines": {
    "node": "22.20.0",
    "pnpm": "10.20.0"
  }
}

每个可执行的工作区包，包括

apps/ui/package.json

和

apps/service/package.json

，都必须声明

"engines": { "node": "22.20.0" }

。项目的

engines.node

字段会拒绝不受支持的运行时。不要仅为此运行时基线添加

engineStrict

：它还会强制执行依赖项的引擎声明，需要根据仓库具体情况做出兼容性决策。

仓库还必须包含一个内容恰好为

22.20.0

的

.nvmrc

文件，且CI或Make构建镜像必须选用Node.js

22.20.0

版本。

engines

是兼容性防护机制；它不会选择构建环境使用的Node二进制文件。

现有Make App在进行UI、认证、过滤、Service或DSL相关工作时，应保留其声明的Node和包管理器版本。这包括兼容的npm和Yarn项目：保留其现有的

package-lock.json

或

yarn.lock

、工作区安装目标和CI工作流。除非用户明确请求运行时迁移，否则不要重写

packageManager

、

engines

、锁文件或Node版本选择文件。迁移应在独立的变更中进行，并包含项目测试和Beta部署。如果管理器声明、锁文件、工作区/CI工作流或目标平台构建要求存在冲突，停止操作并在

make-app-runtime

下报告兼容性阻塞问题；不要生成第二个锁文件，也不要静默将应用转换为pnpm。

对于新的或已明确迁移的pnpm应用，在项目工作前启用Corepack，并使用

corepack pnpm ...

命令运行安装、测试、构建、添加包和发布门禁等操作。Corepack会读取项目声明；全局安装的

pnpm

（包括更新的主版本）不得用于这些应用。对于现有的兼容pnpm应用，通过Corepack使用其声明的pnpm版本。对于未迁移的现有npm或Yarn应用，使用仓库既定的命令和锁文件；不要仅为非相关变更引入Corepack或pnpm。子工作区清单不得声明存在冲突的包管理器版本。

对于新的或已明确迁移的pnpm应用，

apps/package.json

必须提供可运行的脚本，例如

app:ui

、

app:service

、

dev

、

test

和

build

。

corepack pnpm --filter

的目标必须与实际包名（包括作用域名）匹配。遗留应用保留其既定的等效脚本和工作区目标。

make-app-runtime

是

apps/package.json

生成和修复的负责方。

makecli app deploy

不得生成或重写工作区清单。

将

makecli app deploy

视为代码部署边界，除非目标makecli版本被证明运行更严格的发布门禁。不要仅因为部署成功就声称生成的应用已就绪可发布。

在准备新的或已明确迁移的应用发布时，提供足够的项目本地脚本和文档，以便Agent或CI在部署前运行发布就绪检查：

启用Corepack，并使用

corepack pnpm install --frozen-lockfile

为

apps

安装依赖

验证Node.js版本恰好为
```
22.20.0
```
，Corepack版本恰好为
```
0.34.0
```
运行工作区构建
对于Service前置的应用，运行
```
make-app-auth
```
已发布的契约审计
对于每个新的Make App，无论是直连网关还是Service前置，都运行
```
make-app-observability
```
Trace审计和行为测试
当启用单应用权限强制执行或仓库本地交付基线要求时，运行
```
make-app-permission
```
契约审计
运行Service网关模式契约测试，证明本地预览和已发布的上游作用域是分离的
验证
```
apps/ui/dist
```
和
```
apps/service/dist/server.js
```
当存在测试时，运行Service契约测试，包括认证回调代理行为

对于新的或已明确迁移的pnpm Service前置应用，优先使用项目本地的

verify:publish

脚本，通过一条命令运行发布门禁。保留

check:publish

用于构建/产物检查，但不要将其作为唯一的发布门禁。为每个新应用添加

trace:audit

。当启用单应用权限强制执行或本地要求时，向该命令添加

permission:audit

；不要让非相关应用依赖缺失的权限运行时。遗留应用使用其现有的发布命令，并执行等效的适用检查。

针对新的或已明确迁移的pnpm应用的推荐工作区脚本。在将这些添加到

package.json

之前，将审计工具复制或封装到项目本地的

scripts/

目录中；不要将用户特定的技能安装路径写入生成的项目中。在没有明确运行时迁移的情况下，不要将这些pnpm专属脚本复制到遗留的npm/Yarn应用中。

json

{
  "scripts": {
    "check:runtime": "node -e \"if (process.versions.node !== '22.20.0') throw new Error(`Make Apps require Node.js 22.20.0; got ${process.versions.node}`)\" && test \"$(corepack --version)\" = \"0.34.0\"",
    "auth:audit": "node scripts/audit-auth-contract.mjs . --mode service-fronted --published",
    "trace:audit": "node scripts/audit-trace-contract.mjs . --mode service-fronted",
    "schema:diff": "cd .. && makecli diff -f apps/dsl --output=json",
    "check:publish": "corepack pnpm run build && test -f service/dist/server.js && test -d ui/dist",
    "verify:publish": "corepack pnpm run check:runtime && corepack pnpm run test && corepack pnpm run auth:audit && corepack pnpm run trace:audit && corepack pnpm run check:publish && corepack pnpm run schema:diff"
  }
}

对于启用了单应用权限强制执行的应用，添加

"permission:audit": "node scripts/audit-make-app-permission.mjs ."

，并在

verify:publish

后追加

&& corepack pnpm run permission:audit

。

对于直连网关应用，在

trace:audit

中使用

--mode direct

，并保持相同的默认Trace要求。Trace契约本身属于

make-app-observability

；本技能仅确保其检查在部署前运行。

不要将

verify:publish

描述为通用的makecli钩子，除非目标makecli版本支持它。它是在

makecli app deploy

之前运行的项目本地质量门禁。

不要通过

verify:publish

传递后端上下文标志。对于新的或已明确迁移的pnpm应用，使用

corepack pnpm run verify:publish

运行门禁；兼容的遗留应用使用其既定的等效门禁和包管理器。然后使用

makecli app deploy --context <context> --profile <profile> --wait

将代码部署到Beta。遵循

makecli

技能的Beta完成指南，并在获得用户明确授权后，使用

makecli app promote --context <context> --profile <profile> --yes --wait

将该Beta版本发布到生产环境。全程保持相同的后端上下文/配置文件；升级使用已部署的Beta版本，不会推送本地代码。如果项目本地的Node包装器必须通过

corepack pnpm run

接受标志，请在解析前通过移除独立的

--

来规范化argv，因为

corepack pnpm run <script> -- --flag

可能会将该分隔符暴露给脚本。

对于Service前置应用，Service测试套件（通过项目声明的包管理器运行；新的/已迁移的pnpm应用使用

corepack pnpm run test

）必须包含网关模式契约：

MAKE_APP_LOCAL_PREVIEW=true

：Service使用

makecli configure resolve --target local-preview --output=json

的

make_api_origin

字段和

/api/make/**

路径。

发布模式（标志不存在或为false）：Service使用已部署的k8s内部网关源和
```
/make/**
```
路径。
本地预览令牌分支在发布模式下不可达。

Frontend build contract

前端构建契约

Frontend publish artifacts live in

apps/ui/dist

Generated or updated Vite config should set:

```
build.outDir: "dist"
```
```
build.emptyOutDir: true
```

Do not publish or configure static asset discovery against root

dist

apps/dist

前端发布产物位于

apps/ui/dist

。

生成或更新的Vite配置应设置：

```
build.outDir: "dist"
```
```
build.emptyOutDir: true
```

不要针对根目录

dist

或

apps/dist

发布或配置静态资源发现。

Service runtime contract

Service运行时契约

The platform image default Service entry is:

text

/app/apps/service/dist/server.js

Therefore the default TypeScript Service contract is:

source entry:
```
apps/service/src/server.ts
```
compiled entry:
```
apps/service/dist/server.js
```
production start script:
```
node dist/server.js
```
dev script may use
```
tsx watch src/server.ts
```
, but production start must not use
```
tsx
```
Service HTTP port:
```
3000
```
centralized runtime config entry:
```
apps/service/src/config.ts
```

apps/service/tsconfig.json

must compile the runtime source to that path:

json

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.test.ts", "test", "dist"]
}

For a new or explicitly migrated pnpm App,

apps/service/package.json

must include the Node engine and scripts equivalent to:

json

{
  "engines": {
    "node": "22.20.0"
  },
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.json",
    "start": "node dist/server.js",
    "test": "vitest run"
  }
}

Do not leave Docker, K8s, makecli, package scripts, or docs pointing at

/app/apps/service/dist/server.js

unless the project's declared build workflow creates

apps/service/dist/server.js

(for a new or migrated pnpm App,

corepack pnpm --filter <service-package> build

If a legacy project intentionally uses a different Service entry or build tool, keep it only when all runtime references agree: Docker/K8s entrypoint, package

start

, docs, build output, and readiness tests.

平台镜像的默认Service入口为：

text

/app/apps/service/dist/server.js

因此默认的TypeScript Service契约为：

源码入口：
```
apps/service/src/server.ts
```
编译后入口：
```
apps/service/dist/server.js
```
生产环境启动脚本：
```
node dist/server.js
```
开发脚本可以使用
```
tsx watch src/server.ts
```
，但生产环境启动不得使用
```
tsx
```
Service HTTP端口：
```
3000
```
集中式运行时配置入口：
```
apps/service/src/config.ts
```

apps/service/tsconfig.json

必须将运行时源码编译到该路径：

json

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.test.ts", "test", "dist"]
}

对于新的或已明确迁移的pnpm应用，

apps/service/package.json

必须包含等效的Node引擎和脚本：

json

{
  "engines": {
    "node": "22.20.0"
  },
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.json",
    "start": "node dist/server.js",
    "test": "vitest run"
  }
}

不要让Docker、K8s、makecli、包脚本或文档指向

/app/apps/service/dist/server.js

，除非项目声明的构建工作流会生成

apps/service/dist/server.js

（对于新的或已迁移的pnpm应用，使用

corepack pnpm --filter <service-package> build

）。

如果遗留项目有意使用不同的Service入口或构建工具，仅当所有运行时引用（Docker/K8s入口点、包

start

脚本、文档、构建产物和就绪检查）都一致时才保留。

Service build contract test

Service构建契约测试

Service-backed Apps should include a test that protects the runtime entry contract. The test may live in

apps/service/test/service-build-contract.test.ts

or the project's established test location. The fixed-version assertions below apply only to new or explicitly migrated pnpm Apps; legacy Apps assert their own declared runtime and lockfile without changing them.

It should assert:

apps/package.json

declares

packageManager: "pnpm@10.20.0"

apps/package.json

declares

engines.node: "22.20.0"

and

engines.pnpm: "10.20.0"

```
.nvmrc
```
contains
```
22.20.0
```
, and the CI or Make build image uses Node.js
```
22.20.0
```

apps/ui/package.json

and

apps/service/package.json

each declare

engines.node: "22.20.0"

```
apps/service/package.json
```
has a
```
build
```
script
```
apps/service/package.json
```
production start points to
```
node dist/server.js
```
when the platform image uses that entry

apps/service/tsconfig.json

uses

rootDir: "src"

and

outDir: "dist"

after build,
```
apps/service/dist/server.js
```
exists

Run the Service build before relying on that artifact. For a new or explicitly migrated pnpm App:

bash

corepack pnpm --filter <service-package-name> build
test -f apps/service/dist/server.js

For a legacy App, use its established package-manager build command and verify the actual production entry artifact instead.

Service支撑的应用应包含一个保护运行时入口契约的测试。该测试可位于

apps/service/test/service-build-contract.test.ts

或项目既定的测试位置。以下固定版本断言仅适用于新的或已明确迁移的pnpm应用；遗留应用应断言其自身声明的运行时和锁文件，不得更改。

测试应断言：

apps/package.json

声明了

packageManager: "pnpm@10.20.0"

apps/package.json

声明了

engines.node: "22.20.0"

和

engines.pnpm: "10.20.0"

```
.nvmrc
```
包含
```
22.20.0
```
，且CI或Make构建镜像使用Node.js
```
22.20.0
```

apps/ui/package.json

和

apps/service/package.json

各自声明了

engines.node: "22.20.0"

```
apps/service/package.json
```
包含
```
build
```
脚本
当平台镜像使用该入口时，
```
apps/service/package.json
```
的生产环境启动指向
```
node dist/server.js
```

apps/service/tsconfig.json

使用

rootDir: "src"

和

outDir: "dist"

构建后，
```
apps/service/dist/server.js
```
存在

在依赖该产物之前运行Service构建。对于新的或已明确迁移的pnpm应用：

bash

corepack pnpm --filter <service-package-name> build
test -f apps/service/dist/server.js

对于遗留应用，使用其既定的包管理器构建命令，并验证实际的生产环境入口产物。

Runtime config location and port

运行时配置位置与端口

Service runtime environment reads are centralized in

apps/service/src/config.ts

for new projects. This skill only requires the config entry location and fixed port handling needed by runtime/startup. Make adapter variables such as

MAKE_API_BASE_URL

MAKE_SERVER_URL

MAKE_AUTH_BASE_URL

, and

MAKE_BUSINESS_BASE_URL

belong to

make-app-service

Service HTTP port is fixed to

. Generated or refactored Service code,

.env.example

, docs, health checks, tests, CORS, and UI local Service base URL examples must align to

If local

is occupied during development, report the conflict. Do not silently change the Service contract port.

make-app-runtime

does not decide which environment connects to which Make domain, gateway, or API host. Domain mapping, gateway routing, and secret injection belong to backend, operations, Make tooling, or deployed runtime config.

新项目的Service运行时环境读取集中在

apps/service/src/config.ts

中。本技能仅要求运行时/启动所需的配置入口位置和固定端口处理。Make适配器变量（如

MAKE_API_BASE_URL

、

MAKE_SERVER_URL

、

MAKE_AUTH_BASE_URL

和

MAKE_BUSINESS_BASE_URL

）属于

make-app-service

。

Service HTTP端口固定为

。生成或重构的Service代码、

.env.example

、文档、健康检查、测试、CORS以及UI本地Service基础URL示例都必须与

对齐。

如果开发期间本地

端口被占用，报告冲突。不要静默更改Service契约端口。

make-app-runtime

不决定哪个环境连接到哪个Make域、网关或API主机。域名映射、网关路由和密钥注入属于后端、运维、Make工具或已部署的运行时配置范畴。

Forwarded request headers

转发请求头

When Service forwards requests to a Make gateway and that gateway needs request-origin context, preserve or set standard forwarded headers:

```
X-Forwarded-Host
```
```
X-Forwarded-Proto
```

Do not hard-code environment domains in generated Service code. Use the incoming request context or the host runtime proxy contract.

当Service将请求转发到Make网关且该网关需要请求源上下文时，保留或设置标准的转发请求头：

```
X-Forwarded-Host
```
```
X-Forwarded-Proto
```

不要在生成的Service代码中硬编码环境域名。使用传入的请求上下文或主机运行时代理契约。

Readiness checks

就绪检查

Before reporting a Service-backed App as ready to publish or ready for user-domain access, distinguish a new/explicitly migrated pnpm App from a legacy App. For the former:

Verify

node --version

reports

v22.20.0

and

corepack --version

reports

0.34.0

. Then run

cd apps && corepack pnpm install --frozen-lockfile

and verify

corepack pnpm --version

reports

10.20.0

Run

cd apps && corepack pnpm run verify:publish

when the project provides it.

Otherwise, run the workspace build that produces
```
apps/ui/dist
```
.
Run the Service build.
Verify
```
apps/service/dist/server.js
```
exists when the runtime entry points there.
Run the Service contract test and the make-app-auth published audit for Service-fronted Apps.
For Service-fronted Apps, verify the Service contract test covers both local-preview and published gateway modes. Published upstream requests must not use
```
/api/make/**
```
; local preview must consume makecli resolve
```
make_api_origin
```
and must not use k8s-internal
```
/make/**
```
.
If a start smoke is available, start the built Service with the production start script and verify it reaches the expected health or root response, then stop it.

For an existing App without runtime migration, first verify that its declared Node/package manager, lockfile, workspace and CI/install workflow agree with the target platform build image. Use that App's established frozen/clean install, test, build and release commands, then perform the same applicable auth, permission, gateway-mode, artifact and start checks above. Do not require the

22.20.0

10.20.0

triple,

pnpm-workspace.yaml

, or

corepack pnpm run verify:publish

merely because an unrelated UI feature changed. If the platform actually requires a runtime the legacy App cannot meet, report a publish blocker and request an explicit migration; a successful local build alone is not release readiness.

Do not mark a Service-backed App ready based only on successful local

tsx src/server.ts

development startup.

在报告Service支撑的应用已就绪可发布或可用于用户域访问之前，需区分新的/已明确迁移的pnpm应用与遗留应用。对于前者：

验证

node --version

输出

v22.20.0

，

corepack --version

输出

0.34.0

。然后运行

cd apps && corepack pnpm install --frozen-lockfile

，并验证

corepack pnpm --version

输出

10.20.0

。

如果项目提供了

verify:publish

脚本，运行

cd apps && corepack pnpm run verify:publish

。

否则，运行工作区构建以生成
```
apps/ui/dist
```
。
运行Service构建。
当运行时入口指向该路径时，验证
```
apps/service/dist/server.js
```
存在。
对于Service前置应用，运行Service契约测试和make-app-auth已发布审计。
对于Service前置应用，验证Service契约测试同时覆盖本地预览和发布网关模式。已发布的上游请求不得使用
```
/api/make/**
```
；本地预览必须使用makecli resolve返回的
```
make_api_origin
```
，且不得使用k8s内部的
```
/make/**
```
。
如果有启动冒烟测试，使用生产环境启动脚本启动构建后的Service，验证其返回预期的健康检查或根路径响应，然后停止。

对于未进行运行时迁移的现有应用，首先验证其声明的Node/包管理器、锁文件、工作区和CI/安装工作流与目标平台构建镜像一致。使用该应用既定的冻结/干净安装、测试、构建和发布命令，然后执行上述相同的适用认证、权限、网关模式、产物和启动检查。不要仅因为非相关的UI功能变更，就要求使用

22.20.0

10.20.0

三件套、

pnpm-workspace.yaml

或

corepack pnpm run verify:publish

。如果平台实际要求的运行时遗留应用无法满足，报告发布阻塞问题并请求明确迁移；仅本地构建成功并不代表发布就绪。

不要仅基于本地

tsx src/server.ts

开发启动成功，就将Service支撑的应用标记为就绪。

Common failure diagnosis

常见故障诊断

Error:

text

Cannot find module '/app/apps/service/dist/server.js'

Treat it as a runtime contract failure:

build did not run, or
```
src/server.ts
```
was missing, or
```
tsconfig
```
emitted somewhere else, or
package
```
start
```
/ image entry points to a file the build does not create.

Fix the build/start contract. Do not work around it by changing UI code or auth behavior.

错误：

text

Cannot find module '/app/apps/service/dist/server.js'

将其视为运行时契约失败：

构建未运行，或
```
src/server.ts
```
缺失，或
```
tsconfig
```
输出到了其他位置，或
包
```
start
```
脚本/镜像入口指向了构建不会生成的文件。

修复构建/启动契约。不要通过修改UI代码或认证行为来规避此问题。