make-app-runtime

make-app-runtime

在处理 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-integration）。

快速入门

1. 确认任务是否涉及 apps/、apps/service、apps/ui/dist、软件包脚本、Docker/K8s、镜像入口点、发布就绪性，或类似 Cannot find module '/app/apps/service/dist/server.js' 的运行时错误。
2. 除非用户明确表示平台契约本身正在变更，否则应保留平台镜像契约。
3. 对于新 App 或明确的运行时迁移，检查 apps/package.json 中的运行时基线：必须声明 "packageManager": "[email protected]" 和 "engines": { "node": "22.20.0", "pnpm": "10.20.0" }。现有 Make App 在无关任务中应保留其已声明的运行时；只有用户要求明确进行运行时迁移时才更改。
4. 对于新 App 或明确迁移的 App，通过 Corepack（corepack pnpm）运行软件包命令，不要使用环境中已有的 pnpm 二进制文件。对于未进行运行时迁移的现有 App，使用其兼容的已声明软件包管理器、锁文件和既有工作区工作流。
5. 对于新 App 或明确重新组织的 App，检查工作区清单：apps/package.json、apps/pnpm-workspace.yaml、apps/ui/package.json 和 apps/service/package.json。对于旧版 App，应先确认其实际工作区结构，不要直接重写。
6. 宣布就绪前，检查构建产物：前端 apps/ui/dist，以及实际平台镜像所选用的 Service 入口（默认契约为 apps/service/dist/server.js）。
7. 为 Service 运行时入口添加或保留契约测试。

工作区契约

新生成或明确重新组织运行时的 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 必须包含：

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

软件包管理器契约

所有新生成的 Make App React 工作区，以及正在进行明确运行时迁移的现有 App，均使用固定的运行时组合：Node.js 22.20.0、其捆绑的 Corepack 0.34.0 和 pnpm 10.20.0。工作区根目录（apps/package.json）必须声明精确的 Node 和 pnpm 版本：

{
  "packageManager": "[email protected]",
  "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：它还会强制检查依赖项的引擎声明，因此需要根据具体仓库作出兼容性决策。

仓库还必须包含一个 .nvmrc，其内容必须恰好为 22.20.0；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 下报告兼容性阻碍；不要生成第二个锁文件，也不要悄悄将 App 转换为 pnpm。

对于新建或显式迁移为 pnpm 的 App，请在处理项目之前启用 Corepack，并使用 corepack pnpm ... 运行安装、测试、构建、添加包和发布检查。Corepack 会读取项目声明；对于这些 App，不得使用全局安装的 pnpm，包括较新主版本。对于现有且兼容的 pnpm App，请通过 Corepack 使用其声明的 pnpm 版本。对于未迁移的现有 npm 或 Yarn App，请使用仓库已采用的命令和锁文件；不要仅为无关变更而引入 Corepack 或 pnpm。子工作区清单不得声明冲突的包管理器版本。

对于新建或显式迁移为 pnpm 的 App，apps/package.json 必须提供可运行的脚本，例如 app:ui、app:service、dev、test 和 build。corepack pnpm --filter 的目标必须与实际包名一致，包括带作用域的名称。旧版 App 保留其既有的等效脚本和工作区目标。

make-app-runtime 负责生成和修复 apps/package.json。makecli app deploy 不得生成或改写工作区清单。

除非已证明目标 makecli 版本会运行更严格的发布检查，否则请将 makecli app deploy 视为代码部署边界。不要仅因部署成功就声称生成的 App 已具备发布条件。

为新建或显式迁移的 App 准备发布时，请提供足够的项目本地脚本和文档，以便 Agent 或 CI 在部署前运行发布就绪检查：

• 为 apps 启用 Corepack 并安装依赖：corepack pnpm install --frozen-lockfile
• 验证 Node.js 版本恰为 22.20.0，Corepack 版本恰为 0.34.0
• 运行工作区构建
• 对由 Service 提供前端服务的 App，运行 make-app-auth 发布契约审计
• 对每个新建的 Make App（无论是直接网关模式还是由 Service 提供前端服务），运行 make-app-observability Trace 审计和行为测试
• 启用单 App 权限强制，或仓库本地交付基线要求时，运行 make-app-permission 契约审计
• 运行 Service 网关模式契约测试，以证明本地预览范围与已发布的上游范围相互隔离
• 验证 apps/ui/dist 和 apps/service/dist/server.js
• 如果存在测试，则运行 Service 契约测试，包括身份验证回调代理行为测试

对于新建或显式迁移为 pnpm 且由 Service 提供前端服务的 App，优先使用项目本地的 verify:publish 脚本，通过一条命令运行发布检查。保留用于构建／产物检查的 check:publish，但不要将其作为唯一的发布检查。为每个新建 App 添加 trace:audit。启用单 App 权限强制或本地要求时，将 permission:audit 添加到该命令中；不要让无关 App 依赖缺失的权限运行时。旧版 App 使用现有发布命令及适用的等效检查。

新建或显式迁移为 pnpm 的 App 推荐工作区脚本。在将这些脚本添加到 package.json 之前，请将审计工具复制到项目本地的 scripts/ 中，或用这些脚本封装工具；不要在生成的项目中写入特定用户的技能安装路径。未显式迁移运行时的旧版 npm／Yarn App 不得复制这些 pnpm 专用脚本。

{
  "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"
  }
}

对于采用单应用权限强制检查的 App，添加 "permission:audit": "node scripts/audit-make-app-permission.mjs ."，并在 verify:publish 中追加 && corepack pnpm run permission:audit。

对于直接网关 App，在 trace:audit 中使用 --mode direct，并保留相同的默认 Trace 要求。Trace 合约本身属于 make-app-observability；此 Skill 只确保其检查在部署前运行。

除非目标 makecli 版本支持，否则不要将 verify:publish 描述为通用的 makecli 钩子。它是项目本地的质量门禁，应在运行 makecli app deploy 前执行。

不要通过 verify:publish 传递后端上下文标志。对于新建或明确迁移到 pnpm 的 App，运行门禁的命令为 corepack pnpm run verify:publish；兼容的旧版 App 使用其既定的等效门禁和包管理器。然后运行 makecli app deploy --context <context> --profile <profile> --wait，将代码部署到 Beta。按照 makecli Skill 完成 Beta 发布指南中的步骤；获得用户明确授权后，再运行 makecli app promote --context <context> --profile <profile> --yes --wait，将该 Beta 版本发布到 Prod。始终使用相同的后端上下文和配置；晋级会使用已部署的 Beta 版本，不会推送本地代码。如果项目本地的 Node 包装器必须通过 corepack pnpm run 接收标志，则在解析参数前去掉独立的 --，因为 corepack pnpm run <script> -- --flag 可能会将该分隔符传递给脚本。

对于由 Service 提供前端入口的 App，Service 测试套件（通过项目声明的包管理器运行；对于新建或迁移到 pnpm 的 App，运行 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/**。
• 在已发布模式下，无法触达本地预览令牌分支。

前端构建合约

前端发布产物位于 apps/ui/dist。

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

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

不要将静态资源发现配置为针对根目录下的 dist 或 apps/dist，也不要发布这些目录。

Service 运行时合约

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

/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 必须将运行时源码编译到该路径：

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

对于新建或明确迁移到 pnpm 的 App，apps/service/package.json 必须包含等效的 Node 引擎版本和脚本：

{
  "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"
  }
}

除非项目声明的构建工作流会生成 apps/service/dist/server.js（对于新建或迁移到 pnpm 的 App，运行 corepack pnpm --filter <service-package> build），否则不要让 Docker、K8s、makecli、包脚本或文档指向 /app/apps/service/dist/server.js。

如果旧版项目有意使用不同的 Service 入口或构建工具，则仅当所有运行时引用保持一致时才保留：Docker/K8s 入口点、包脚本 start、文档、构建输出和就绪状态测试。

Service 构建契约测试

由 Service 支持的 App 应包含一项测试，用于保障运行时入口契约。测试可以放在 apps/service/test/service-build-contract.test.ts，也可以放在项目既定的测试位置。以下固定版本断言仅适用于新建或明确迁移的 pnpm App；旧版 App 应验证自身声明的运行时和锁文件，不作更改。

测试应断言：

• apps/package.json 声明 packageManager: "[email protected]"
• 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 脚本
• 当平台镜像使用 node dist/server.js 作为入口时，apps/service/package.json 的生产启动命令应指向该入口
• apps/service/tsconfig.json 使用 rootDir: "src" 和 outDir: "dist"
• 构建后，apps/service/dist/server.js 存在

依赖此构建产物前，请先运行 Service 构建。对于新建或明确迁移的 pnpm App：

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

对于旧版 App，请使用其既定的包管理器构建命令，并验证实际的生产入口产物。

运行时配置位置和端口

对于新项目，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 端口固定为 3000。生成或重构的 Service 代码、.env.example、文档、健康检查、测试、CORS，以及 UI 本地 Service 基础 URL 示例都必须与 3000 保持一致。

如果开发期间本地端口 3000 已被占用，请报告冲突。不要擅自更改 Service 契约端口。

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

转发请求标头

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

• X-Forwarded-Host
• X-Forwarded-Proto

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

就绪检查

在报告基于 Service 的 App 已可发布或可供用户通过域名访问之前，请区分新建／已明确迁移的 pnpm App 与旧版 App。对于前者：

1. 确认 node --version 显示 v22.20.0，且 corepack --version 显示 0.34.0。然后运行 cd apps && corepack pnpm install --frozen-lockfile，并确认 corepack pnpm --version 显示 10.20.0。
2. 如果项目提供 cd apps && corepack pnpm run verify:publish，请运行。
3. 否则，运行会生成 apps/ui/dist 的工作区构建。
4. 运行 Service 构建。
5. 如果运行时入口指向 apps/service/dist/server.js，请确认该文件存在。
6. 对由 Service 提供前端服务的 App，运行 Service 合约测试和 make-app-auth 发布审计。
7. 对由 Service 提供前端服务的 App，请确认 Service 合约测试覆盖本地预览和已发布网关模式。已发布环境中的上游请求不得使用 /api/make/**；本地预览必须使用 makecli 解析出的 make_api_origin，且不得使用 k8s 内部的 /make/**。
8. 如果可以进行启动冒烟测试，请使用生产启动脚本启动构建后的 Service，并确认其返回预期的健康检查或根路径响应，然后停止它。

对于未进行运行时迁移的现有 App，首先确认其声明的 Node／包管理器、锁文件、工作区和 CI／安装工作流与目标平台构建镜像一致。使用该 App 已有的冻结／干净安装、测试、构建和发布命令，然后执行上述适用的相同认证、权限、网关模式、产物和启动检查。不要仅因 UI 功能发生了与运行时无关的更改，就要求使用 22.20.0／10.20.0 组合、pnpm-workspace.yaml 或 corepack pnpm run verify:publish。如果平台确实要求旧版 App 无法满足的运行时，请报告发布阻碍并请求明确迁移；仅在本地构建成功并不代表已具备发布条件。

不得仅凭本地 tsx src/server.ts 开发启动成功，就将基于 Service 的 App 标记为就绪。

常见故障诊断

错误：

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

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

• 未运行构建，或
• 缺少 src/server.ts，或
• tsconfig 将文件输出到了其他位置，或
• 软件包的 start 命令／镜像入口指向了构建不会生成的文件。

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