@wdyy/skills 0.1.17 → 0.1.18

package/.well-known/skills/index.json

@@ -7,7 +7,7 @@
     },
     {
       "name": "wdyy-deployment-standard",
-      "description": "为无 CI/CD 的前后端项目生成并验证跨宿主机统一 Docker 交付：在 Linux、macOS Docker Desktop 或 Windows Docker Desktop + WSL2/Linux 容器模式中，使用本地已有基础镜像构建单一 linux/amd64 或 linux/arm64 双镜像包，并在平台匹配的 Linux engine 上以固定端口、容器名、重启策略和 CST（UTC+8）时间整栈运行。Use when 规划、实现、审查或执行跨构建机平台的人工 Docker 生产交付时。",
+      "description": "为无 CI/CD 的前后端项目生成并验证跨宿主机统一 Docker 交付：在 Linux、macOS Docker Desktop 或 Windows Docker Desktop + WSL2/Linux 容器模式中，使用本地已有基础镜像构建单一 linux/amd64 或 linux/arm64 双镜像包，支持 macOS/arm64 以仿真运行 amd64 镜像，并以固定端口、容器名、重启策略和 CST（UTC+8）时间整栈运行。Use when 规划、实现、审查或执行跨构建机平台的人工 Docker 生产交付时。",
       "files": ["SKILL.md", "agents/openai.yaml", "reference/docker-delivery-rules.md", "scripts/generate-deployment-files.mjs", "scripts/generate-deployment-files.test.mjs", "scripts/validate-deployment-package.mjs", "scripts/validate-deployment-package.test.mjs", "templates/backend.Dockerfile.template", "templates/frontend.Dockerfile.template", "templates/frontend-container.conf.template", "templates/env.example.template", "templates/deploy.sh.template", "templates/docker-compose.yml", "templates/dockerignore.template"]
     },
     {

package/.well-known/skills/wdyy-api-standard/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wdyy-api-standard
 description: 根据“获取XX数据”“使用XX接口”“使用指定查询名称”等具体需求，定位已登记的接口 reference；对于 HIS SQL 查询，从远程查询目录按 name 精确匹配，并按已确认的接口契约将调用方式写入程序。Use when 需要查询或实现一个已登记接口或 HIS SQL 查询的数据调用时。
+disable-model-invocation: true
 ---
 
 # 接口路由

package/.well-known/skills/wdyy-deployment-standard/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: wdyy-deployment-standard
-description: 为无 CI/CD 的前后端项目生成并验证跨宿主机统一 Docker 交付：在 Linux、macOS Docker Desktop 或 Windows Docker Desktop + WSL2/Linux 容器模式中，使用本地已有基础镜像构建单一 linux/amd64 或 linux/arm64 双镜像包，并在平台匹配的 Linux engine 上以固定端口、容器名、重启策略和 CST（UTC+8）时间整栈运行。Use when 规划、实现、审查或执行跨构建机平台的人工 Docker 生产交付时。
+description: 为无 CI/CD 的前后端项目生成并验证跨宿主机统一 Docker 交付：在 Linux、macOS Docker Desktop 或 Windows Docker Desktop + WSL2/Linux 容器模式中，使用本地已有基础镜像构建单一 linux/amd64 或 linux/arm64 双镜像包，支持 macOS/arm64 以仿真运行 amd64 镜像，并以固定端口、容器名、重启策略和 CST（UTC+8）时间整栈运行。Use when 规划、实现、审查或执行跨构建机平台的人工 Docker 生产交付时。
 ---
 
 # 统一 Docker 交付规范
 
 ## Overview
 
-把一个项目作为一个整体交付：在 Linux、macOS Docker Desktop，或 Windows Docker Desktop + WSL2/Linux 容器模式中执行 `./deploy.sh build`，按 `DOCKER_PLATFORM` 生成前端、后端两个 Linux 单架构镜像并分别导出，最终只产出一个压缩包；工程师人工复制并解压；Docker Server 平台匹配时无参数执行 `./deploy.sh`，一次性加载并部署整个前后端项目栈。
+把一个项目作为一个整体交付：在 Linux、macOS Docker Desktop，或 Windows Docker Desktop + WSL2/Linux 容器模式中执行 `./deploy.sh build`，按 `DOCKER_PLATFORM` 生成前端、后端两个 Linux 单架构镜像并分别导出，最终只产出一个压缩包；工程师人工复制并解压；Docker Server 支持目标执行方式时无参数执行 `./deploy.sh`，一次性加载并部署整个前后端项目栈。
 
-macOS/arm64 宿主机的 Docker Server 平台是 `linux/arm64`。Windows 必须在启用 Docker Desktop 集成的 WSL2 发行版和 Linux 文件系统中执行同一 Bash 脚本，并使用 Linux 容器 engine；不支持原生 PowerShell、Windows 容器模式或 `windows/*` 镜像。
+macOS/arm64 宿主机的 Docker Server 通常报告 `linux/arm64`，但可以通过 `--platform linux/amd64` 仿真运行 amd64 镜像；是否兼容必须由禁止拉取的目标镜像探针、健康检查和业务验收实际证明。Windows 必须在启用 Docker Desktop 集成的 WSL2 发行版和 Linux 文件系统中执行同一 Bash 脚本，并使用 Linux 容器 engine；不支持原生 PowerShell、Windows 容器模式或 `windows/*` 镜像。
 
 ## Workflow
 
-1. 读取目标项目真实的 pnpm scripts、前后端构建输出、Dockerfile、健康检查、根 `.env` 和远程数据库连接方式。
+1. 读取目标项目真实的 pnpm scripts、前后端构建输出、Dockerfile、健康检查、根 `.env` 和远程数据库连接方式。若 frontend 使用 Vite，确认只有 `serve` 校验 `FRONTEND_URL`、`FRONTEND_PORT`、`VITE_DEV_PROXY_TARGET`，生产 `build` 不依赖这些开发服务器变量。
 2. 完整读取 [统一 Docker 交付规则](reference/docker-delivery-rules.md)。
 3. 运行 `node scripts/generate-deployment-files.mjs --target <目标项目根目录> --write` 生成受版本控制文件并扩充 `.env`、`.env.example` 的部署段。既有生成文件不一致时先展示差异并等待工程师确认，确认后才使用 `--force`。
 4. 在目标项目根执行生成器 `--check`，再运行 `scripts/validate-deployment-package.mjs` 和行为测试。
@@ -25,9 +25,11 @@ macOS/arm64 宿主机的 Docker Server 平台是 `linux/arm64`。Windows 必须
 - 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest` 两个独立镜像。
 - 每个交付包只对应 `DOCKER_PLATFORM` 指定的 `linux/amd64` 或 `linux/arm64`；构建机自身平台可以不同，不得回退到构建机原生架构。
 - 分别导出 `frontend-image.tar`、`backend-image.tar`，但只交付一个 `<PROJECT_NAME>-docker.tar.gz`。
-- 构建前检查 `FRONTEND_BASE_IMAGE`、`BACKEND_BASE_IMAGE` 已存在于本地；缺失即失败，不执行 `docker pull`。
-- 宿主机可以是 Linux、macOS 或 Windows，但镜像和 Docker Server 必须是 `linux/amd64` 或 `linux/arm64`；加载前读取 Server OS/架构，无法读取、Windows 容器模式或不等于 `DOCKER_PLATFORM` 时立即失败。
+- 构建前检查 `FRONTEND_BASE_IMAGE`、`BACKEND_BASE_IMAGE` 已存在于本地，并使用 `--pull=never --platform "$DOCKER_PLATFORM"` 的一次性容器探针验证实际选中的目标平台子镜像架构；缺失即失败，不执行 `docker pull`，不以多平台索引的默认元数据代替实际选择结果。
+- 宿主机可以是 Linux、macOS 或 Windows，镜像与 Docker Server 必须是受支持的 Linux 平台；加载前读取 Server OS/架构，无法读取或 Windows 容器模式时立即失败。仅允许 macOS 执行宿主机在 `linux/arm64` Server 上加载 `linux/amd64` 包；其他 Server/目标架构不匹配继续失败。
+- macOS/arm64 加载 amd64 包后、Compose 状态变化前，必须对两个已加载镜像执行 `--pull=never --platform linux/amd64` 目标探针；失败时不得切换平台、pull、fallback 或声称兼容成功。
 - Compose 只定义 frontend、backend；数据库通过 `.env` 直连远程实例，不生成数据库容器、数据卷或迁移路径。
+- backend 必须以原变量名显式接收 `BACKEND_URL`、`BACKEND_PORT`，不得映射或在镜像中重复设置应用未读取的 `HOST`、`PORT`；生成器和交付包校验器必须拒绝旧变量。
 - 服务器无参数命令整体部署；只额外允许 `stop` 和 `status`，不得独立操作单一服务。
 - 前后端直接暴露 `.env` 指定的宿主机端口；两个容器共同挂载项目根 `./logs` 到 `/app/logs`。
 - `FRONTEND_PORT` 同时控制 frontend 宿主机映射和容器 Nginx 监听；`BACKEND_PORT` 同时控制 backend 宿主机映射、Node 监听、健康检查和 frontend 内部代理，不增加重复容器端口变量。
@@ -36,6 +38,8 @@ macOS/arm64 宿主机的 Docker Server 平台是 `linux/arm64`。Windows 必须
 - frontend Nginx 使用 `.env` 的 `VITE_API_BASE_URL` 与 `BACKEND_PORT`，把同源 API 请求代理到 Compose `backend` 服务；`VITE_API_BASE_URL` 必须等于 `/${API_PREFIX}`。
 - 根 `.env` 与 `.env.example` 必须严格使用 `TZ=Asia/Shanghai`。构建后、Docker save 前实际探测两个镜像；整栈健康后实际探测两个运行容器，均必须以 24 小时格式输出 `CST +0800`。
 - `.env` 可以进入人工上传的压缩包，但必须被 `.dockerignore` 排除，不得进入镜像。
+- 宿主机端口占用时先只读确认监听进程、容器和项目归属；不得自动停止或杀死进程，确认属于当前项目后再正常停止并重新整栈部署。
+- 容器健康后仍须执行真实登录和核心业务查询。若出现关系或表不存在，先只读核对 schema、迁移记录和业务表；迁移与种子按 `wdyy-database-standard` 单独确认，不进入 Docker 自动部署。
 
 ## Prohibited
 
@@ -43,6 +47,8 @@ macOS/arm64 宿主机的 Docker Server 平台是 `linux/arm64`。Windows 必须
 - 不得保留发布账本、版本目录、`release.env`、交互菜单或前后端独立替换命令。
 - 不得上传文件、拉取代码、安装 Docker、固定服务器目录或使用 `source`、`eval` 执行 `.env`。
 - 不得生成 PowerShell 备用脚本、Windows 镜像或自动切换 Docker Desktop engine；Windows 原生容器模式必须明确失败。
+- 不得把 amd64 仿真描述为无条件兼容，不得自动安装或启用 Rosetta、QEMU、binfmt 等仿真能力。
+- 不得自动停止端口占用进程或自动执行数据库迁移、种子。
 - 不得跳过清单、镜像标签、Compose 服务范围、远程数据库配置或健康状态验证。
 
 ## Verification
@@ -51,13 +57,15 @@ macOS/arm64 宿主机的 Docker Server 平台是 `linux/arm64`。Windows 必须
 - [ ] 压缩包解压后只含 `.env`、deploy.sh、docker-compose.yml、两个镜像 tar 和 manifest.sha256。
 - [ ] 两个镜像归档各自只含预期的 `latest` 标签。
 - [ ] 单一压缩包不含 macOS AppleDouble、资源叉或扩展属性元数据。
-- [ ] 构建与服务器 Compose 均禁止 pull，服务器禁止 build；基础镜像、构建参数、产出镜像和 Compose 平台均与 `DOCKER_PLATFORM` 一致。
-- [ ] Linux Engine、macOS/arm64 Docker Desktop 与 Windows Docker Desktop + WSL2 场景使用同一包契约；Windows 原生容器模式被拒绝。
-- [ ] Docker Server 平台在加载镜像前通过校验，并严格等于 `DOCKER_PLATFORM`。
+- [ ] 构建与服务器 Compose 均禁止 pull，服务器禁止 build；基础镜像和产出镜像均通过目标平台一次性容器探针验证，构建参数和 Compose 平台均与 `DOCKER_PLATFORM` 一致。
+- [ ] Linux Engine、macOS/arm64 Docker Desktop 与 Windows Docker Desktop + WSL2 场景使用同一包契约；Windows 原生容器模式被拒绝，macOS/arm64 可通过实际探针运行 amd64 包。
+- [ ] Docker Server 支持范围在加载镜像前通过校验；macOS/arm64 的 amd64 例外在加载后、Compose 前通过目标镜像探针验证，其他架构不匹配被拒绝。
 - [ ] Compose 只含 frontend、backend，并使用远程数据库环境变量和根 logs。
+- [ ] backend 显式环境项使用 `BACKEND_URL`、`BACKEND_PORT` 原名，后端镜像和运行容器均不存在 `HOST`、`PORT` 旧变量。
 - [ ] Compose 的双向端口都来自 FRONTEND_PORT/BACKEND_PORT；两个固定容器名等于各自镜像 repository，并各使用 `unless-stopped`。
 - [ ] 根 `.env` 严格使用 `TZ=Asia/Shanghai`；两个镜像和两个运行容器的真实时间探测均为 24 小时制 `CST +0800`。
 - [ ] frontend 镜像不包含 `.env`，同源 API 代理能够把真实页面查询转发到 backend。
+- [ ] Vite 生产构建不要求开发服务器变量；端口占用和数据库缺表均按只读诊断、确认后处理的边界执行。
 - [ ] 无参数部署、stop、status 的实际行为及失败传播通过测试。
 
 任一步失败必须指出具体阶段并返回非零；不得静默跳过、伪造成功或删除上一份成功交付包。

package/.well-known/skills/wdyy-deployment-standard/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "wdyy-deployment-standard"
-  short_description: "跨 Linux、Mac 与 Windows WSL2 生成并验证统一双镜像交付"
-  default_prompt: "Use $wdyy-deployment-standard to build and run a single-target linux/amd64 or linux/arm64 dual-image package on Linux engines, macOS Docker Desktop, or Windows Docker Desktop through WSL2, with deterministic ports, names, restart policy, and CST UTC+8 time."
+  short_description: "跨 Linux、Mac 与 Windows WSL2 生成并验证单架构双镜像交付"
+  default_prompt: "Use $wdyy-deployment-standard to build and run one linux/amd64 or linux/arm64 dual-image package on Linux engines, macOS Docker Desktop including verified amd64 emulation on Apple silicon, or Windows Docker Desktop through WSL2, with deterministic ports, names, restart policy, and CST UTC+8 time."

package/.well-known/skills/wdyy-deployment-standard/reference/docker-delivery-rules.md

@@ -46,7 +46,7 @@ TZ=Asia/Shanghai
 - `.env` 权限必须为 `0600` 或只读 `0400`。
 - 按数据解析 `.env`；不得 `source`、`eval` 或执行其中内容。
 - `DB_URL` 指向远程数据库主机或地址；部署资产不得把它解释为 Docker 服务名并创建数据库容器。
-- `DOCKER_PLATFORM` 必须为 `linux/amd64` 或 `linux/arm64`，表示当前单一交付包的镜像目标平台，并与运行时 Docker Server 平台一致；不得根据 Linux、macOS、Windows 宿主机或 CPU 自动改写，不得使用 `darwin/*` 或 `windows/*`。
+- `DOCKER_PLATFORM` 必须为 `linux/amd64` 或 `linux/arm64`，只表示当前单一交付包的镜像和 Compose 目标平台；不得根据 Linux、macOS、Windows 宿主机或 CPU 自动改写，不得使用 `darwin/*` 或 `windows/*`。macOS/arm64 Docker Desktop 可以在 `linux/arm64` Server 上通过仿真运行 `linux/amd64`，但必须由目标镜像探针、健康检查和业务验收实际证明。
 - `TZ` 必须严格等于 `Asia/Shanghai`，使两个容器统一使用 24 小时制的 CST（UTC+8）；其他合法 IANA 时区也不属于本交付合同。
 - `API_PREFIX` 只允许一个安全路径段，`VITE_API_BASE_URL` 必须严格等于 `/${API_PREFIX}`；生成器在两个键都缺失时加入标准值，存在缺失或冲突时明确失败。
 - `.env.example` 可保留空数据库凭据，但真实 `.env` 构建时必须完整。
@@ -55,11 +55,13 @@ TZ=Asia/Shanghai
 
 基础镜像引用允许使用标签，但目标架构版本必须在构建机本地预先存在。构建命令可以在 Linux、macOS Docker Desktop，或 Windows Docker Desktop + WSL2/Linux 容器模式中执行，也可以与目标架构不同；Windows 必须从启用 Docker Desktop 集成的 WSL2 发行版和 Linux 文件系统执行，不支持原生 PowerShell 或 Windows 容器模式。相同标签被人工替换后可能对应不同内容，构建过程不得访问镜像仓库或回退到构建机原生架构。
 
+若 frontend 使用 Vite，配置必须通过 `defineConfig(({ command, mode }) => ...)` 或等价方式区分命令：仅 `command === 'serve'` 时读取、校验并配置 `FRONTEND_URL`、`FRONTEND_PORT`、`VITE_DEV_PROXY_TARGET`；`command === 'build'` 时只读取 `VITE_API_BASE_URL` 等真实构建配置。生产构建上下文不包含根 `.env` 时仍必须通过 frontend lint、测试和 `pnpm build`，不得为了构建复制根 `.env`。
+
 `./deploy.sh build` 必须按顺序：
 
 1. 验证根 `.env`、Dockerfile、Compose 和 `.dockerignore`。
-2. 使用平台感知的 `docker image inspect --platform "$DOCKER_PLATFORM"` 确认两个基础镜像的目标架构版本存在。
-3. 校验本地基础镜像平台与 `DOCKER_PLATFORM` 一致，使用 `docker build --pull=false --platform "$DOCKER_PLATFORM"` 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest`，并校验产出镜像平台。
+2. 保留普通 `docker image inspect <image>` 作为标签存在性检查，再通过 `docker run --rm --pull=never --platform "$DOCKER_PLATFORM" --entrypoint uname <image> -m` 实际选择目标平台子镜像并验证机器架构：`linux/amd64` 必须输出 `x86_64`，`linux/arm64` 必须输出 `aarch64` 或 `arm64`。目标子镜像缺失时必须失败，禁止 pull。
+3. 使用 `docker build --pull=false --platform "$DOCKER_PLATFORM"` 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest`，并用同一目标平台一次性容器探针校验产出镜像。Docker Desktop 的 containerd 镜像存储可让一个标签指向多平台索引，`docker image inspect --platform` 可能返回索引默认平台或不完整元数据，不得用它判定目标子镜像是否存在或架构是否匹配。
 4. 对两个产出镜像分别使用 `docker run --rm --pull=never --platform "$DOCKER_PLATFORM"` 探测 `date '+%H %Z %z'`，要求小时为 `00`–`23`、时区为 `CST +0800`。
 5. 分别执行 Docker save，生成 `frontend-image.tar`、`backend-image.tar`。
 6. 复制根 `.env`、deploy.sh、docker-compose.yml，生成覆盖全部包内文件的 `manifest.sha256`。
@@ -87,8 +89,9 @@ manifest.sha256
 
 工程师人工复制并解压单一压缩包。部署根由解压后的 deploy.sh 物理路径确定。Windows Docker Desktop 场景必须把包放在 WSL2 Linux 文件系统中；不能满足 `.env` owner-only 权限的 Windows 挂载目录必须失败。复制用的 `.tar.gz` 必须放在部署根外，或在解压后移出部署根；执行 `./deploy.sh` 时，部署根只允许保留压缩包契约中的 6 个文件和运行后生成的 `logs/` 目录。
 
-- `./deploy.sh`：校验 `.env` 权限和内容、清单、两个镜像 tar 及预期标签；通过 `docker version` 读取 Docker Server OS/架构并要求是与 `DOCKER_PLATFORM` 相等的 Linux engine；检查固定容器名不存在或属于当前 Compose 项目和对应服务；校验通过后才加载两个镜像，再使用一次 `docker compose up -d --force-recreate --no-build --pull never --wait frontend backend` 整体部署并等待健康，最后在两个运行容器中验证 24 小时制 `CST +0800`。
-- 加载后必须再次校验两个镜像与 `DOCKER_PLATFORM` 一致；Compose 的两个服务也必须显式声明同一平台。
+- `./deploy.sh`：校验 `.env` 权限和内容、清单、两个镜像 tar 及预期标签；通过 `docker version` 读取 Docker Server OS/架构，无法读取、Windows 容器模式或不受支持的平台立即失败；检查固定容器名不存在或属于当前 Compose 项目和对应服务；校验通过后才加载两个镜像，再使用一次 `docker compose up -d --force-recreate --no-build --pull never --wait frontend backend` 整体部署并等待健康，最后在两个运行容器中验证 24 小时制 `CST +0800`。
+- Docker Server 架构通常必须等于 `DOCKER_PLATFORM`。唯一例外是脚本实际运行于 macOS、Docker Server 为 `linux/arm64`、交付包为 `linux/amd64`；该场景允许加载镜像，但加载后必须用禁止拉取的 `--platform linux/amd64` 一次性容器探针验证两个镜像均实际输出 `x86_64`，再进入 Compose。探针失败必须明确终止，不切换平台、不 pull、不 fallback。
+- 加载后必须用禁止拉取的目标平台一次性容器探针再次校验两个镜像与 `DOCKER_PLATFORM` 一致；Compose 的两个服务也必须显式声明同一平台。amd64 仿真可能更慢或存在二进制限制，不得仅凭 Server 平台或静态镜像元数据声称兼容。
 - `./deploy.sh stop`：同时停止 frontend、backend，保留容器、镜像、交付文件和日志。
 - `./deploy.sh status`：输出当前 Compose 项目的服务状态，不改变 Docker 状态。
 
@@ -103,12 +106,16 @@ manifest.sha256
 - frontend Nginx 把 `${VITE_API_BASE_URL}/...` 原样代理到 `http://backend:${BACKEND_PORT}`；不得硬编码服务器地址或后端端口。
 - 两个服务均使用根 `.env`，显式接收同一 `TZ`，并挂载 `./logs:/app/logs`。
 - backend 直接读取 DB_URL、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME、DB_SCHEMA。
+- backend 显式接收 `${BACKEND_URL:?BACKEND_URL is required}` 与 `${BACKEND_PORT:?BACKEND_PORT is required}`，变量名必须与应用契约一致；Compose 和后端镜像均不得改写或重复设置 `HOST`、`PORT`。
 - Compose 不得定义数据库服务、数据库镜像、数据库 volume、数据库端口映射或迁移任务。
 - 前端 Nginx 日志写入 `/app/logs/frontend-access.log`、`/app/logs/frontend-error.log`；后端遵循 wdyy-logging-standard；部署操作写入 `./logs/deploy.log`。
 
+容器健康只证明健康检查端点，不证明数据库业务表已初始化。部署后必须执行真实登录、核心查询和详情读取；出现 `relation "..." does not exist` 或等价缺表错误时，先只读核对远程数据库目标 schema、迁移记录、业务表和必要种子。需要写入时使用 `wdyy-database-standard`，展示迁移与种子范围并等待工程师确认；部署脚本不得自动执行。
+
 ## 7. 失败边界
 
-- 目标架构基础镜像缺失、Docker Server 平台无法读取或不匹配、Windows 容器模式、同名容器所有权冲突、TZ 不等于 `Asia/Shanghai`、镜像或运行容器时间不是 24 小时制 `CST +0800`、清单错误、镜像标签错误、远程数据库配置不完整或任一服务不健康时明确失败。
+- 目标架构基础镜像缺失、Docker Server 平台无法读取或不受支持、非 macOS 已确认例外的 Server/目标架构不匹配、macOS amd64 目标镜像探针失败、Windows 容器模式、同名容器所有权冲突、TZ 不等于 `Asia/Shanghai`、镜像或运行容器时间不是 24 小时制 `CST +0800`、清单错误、镜像标签错误、远程数据库配置不完整或任一服务不健康时明确失败。
 - 禁止 `docker pull`、服务器 `docker build`、镜像 fallback、自动回滚、自动安装和静默跳过。
 - 脚本只操作当前 `PROJECT_NAME` 的 Compose 项目和 frontend、backend 服务，不清理其他项目资源。
 - 旧部署资产由工程师根据实际状态单独迁移；新脚本不得猜测并删除。
+- 宿主机端口绑定失败时，先用只读命令确认监听进程、容器和项目归属；不得自动 kill、stop 或删除。仅在确认属于当前项目后正常停止旧进程，再重新执行整栈部署。

package/.well-known/skills/wdyy-deployment-standard/scripts/generate-deployment-files.test.mjs

@@ -84,6 +84,9 @@ test('生成统一 Docker 交付文件并通过确定性检查', async () => {
   assert.equal((compose.match(/restart: unless-stopped/g) ?? []).length, 2);
   assert.match(compose, /"\$\{DOCKER_BIND_IP\}:\$\{FRONTEND_PORT\}:\$\{FRONTEND_PORT\}"/);
   assert.match(compose, /"\$\{DOCKER_BIND_IP\}:\$\{BACKEND_PORT\}:\$\{BACKEND_PORT\}"/);
+  assert.match(compose, /BACKEND_URL: "\$\{BACKEND_URL:\?BACKEND_URL is required\}"/);
+  assert.equal((compose.match(/BACKEND_PORT: "\$\{BACKEND_PORT:\?BACKEND_PORT is required\}"/g) ?? []).length, 2);
+  assert.doesNotMatch(compose, /^\s+(?:HOST|PORT):/m);
   const nginx = await readFile(join(root, 'scripts/deployment/frontend-container.conf.template'), 'utf8');
   assert.match(nginx, /location \$\{VITE_API_BASE_URL\}\/ \{/);
   assert.match(nginx, /proxy_pass http:\/\/backend:\$\{BACKEND_PORT\};/);
@@ -95,6 +98,7 @@ test('生成统一 Docker 交付文件并通过确定性检查', async () => {
   assert.match(backendDockerfile, /WORKDIR \/app\n/);
   assert.match(backendDockerfile, /COPY --from=build \/runtime \.\/src\/backend\//);
   assert.match(backendDockerfile, /CMD \["node", "src\/backend\/dist\/main\.js"\]/);
+  assert.doesNotMatch(backendDockerfile, /^ENV\s+(?:HOST|PORT)=/m);
   const check = await invoke(root, '--check');
   assert.match(check.stdout, /verified unified Docker delivery files/);
   assert.match(await readFile(join(root, 'deploy.sh'), 'utf8'), /env COPYFILE_DISABLE=1 tar --no-xattrs -czf "\$candidate"/);

package/.well-known/skills/wdyy-deployment-standard/scripts/validate-deployment-package.mjs

@@ -81,12 +81,15 @@ for (const [pattern, message] of [
   [/"\$1" == status/, 'Missing status command'],
   [/docker image inspect "\$FRONTEND_BASE_IMAGE"/, 'Frontend local base image must be checked'],
   [/docker image inspect "\$BACKEND_BASE_IMAGE"/, 'Backend local base image must be checked'],
+  [/docker run --rm --pull=never --platform "\$DOCKER_PLATFORM" --entrypoint uname "\$image" -m/, 'Image platforms must be verified by selecting the local target-platform child without pulling'],
   [/docker build --pull=false --platform "\$DOCKER_PLATFORM"/g, 'Docker builds must use the configured target platform and disable pull'],
   [/docker save -o "\$package_root\/frontend-image\.tar"/, 'Frontend image must be exported separately'],
   [/docker save -o "\$package_root\/backend-image\.tar"/, 'Backend image must be exported separately'],
   [/env COPYFILE_DISABLE=1 tar --no-xattrs -czf "\$candidate"/, 'Delivery archive must exclude macOS metadata and extended attributes'],
   [/docker version --format '\{\{\.Server\.Os\}\}\/\{\{\.Server\.Arch\}\}'/, 'Deploy must read the Docker Server platform'],
   [/Windows container mode is unsupported; switch Docker Desktop to Linux containers/, 'Deploy must reject Windows container mode explicitly'],
+  [/\[\[ "\$EXECUTION_KERNEL" == Darwin && "\$actual" == linux\/arm64 && "\$DOCKER_PLATFORM" == linux\/amd64 \]\]/, 'Deploy must allow only the confirmed macOS arm64-to-amd64 emulation exception'],
+  [/only macOS with linux\/arm64 Docker Server may run linux\/amd64 through verified emulation/, 'Deploy must reject every other Docker Server target mismatch explicitly'],
   [/assert_stack_container_ownership/, 'Deploy must validate fixed container name ownership'],
   [/assert_image_cst_time "\$frontend_image"/, 'Frontend built image CST time must be checked'],
   [/assert_image_cst_time "\$backend_image"/, 'Backend built image CST time must be checked'],
@@ -97,14 +100,19 @@ for (const [pattern, message] of [
   [/compose ps frontend backend/, 'Status must inspect both services'],
 ]) assert(pattern.test(deploy), message);
 assert((deploy.match(/docker build --pull=false --platform "\$DOCKER_PLATFORM"/g) ?? []).length === 2, 'Exactly two Docker builds must use the configured target platform and disable pull');
+assert(!/docker image inspect --platform/.test(deploy), 'Multi-platform image index metadata must not be used for target-platform validation');
 const deployStackIndex = deploy.indexOf('deploy_stack() {');
 const serverPlatformCheckIndex = deploy.indexOf('  assert_server_platform\n', deployStackIndex);
 const ownershipCheckIndex = deploy.indexOf('  assert_stack_container_ownership\n', deployStackIndex);
 const firstImageLoadIndex = deploy.indexOf('  docker load -i ', deployStackIndex);
+const secondImageLoadIndex = deploy.indexOf('  docker load -i "$DEPLOY_ROOT/backend-image.tar"', firstImageLoadIndex);
+const loadedFrontendPlatformCheckIndex = deploy.indexOf('  assert_image_platform "${PROJECT_NAME}_frontend:latest"', secondImageLoadIndex);
+const loadedBackendPlatformCheckIndex = deploy.indexOf('  assert_image_platform "${PROJECT_NAME}_backend:latest"', loadedFrontendPlatformCheckIndex);
 const composeUpIndex = deploy.indexOf('  compose up -d --force-recreate --no-build --pull never --wait frontend backend', deployStackIndex);
 const runningTimeCheckIndex = deploy.indexOf('  assert_container_cst_time "${PROJECT_NAME}_frontend"', deployStackIndex);
 assert(deployStackIndex >= 0 && serverPlatformCheckIndex > deployStackIndex && ownershipCheckIndex > serverPlatformCheckIndex && firstImageLoadIndex > ownershipCheckIndex, 'Docker Server platform and container ownership must be checked before loading images');
-assert(composeUpIndex > firstImageLoadIndex && runningTimeCheckIndex > composeUpIndex, 'Running container CST time must be checked after Compose health wait');
+assert(secondImageLoadIndex > firstImageLoadIndex && loadedFrontendPlatformCheckIndex > secondImageLoadIndex && loadedBackendPlatformCheckIndex > loadedFrontendPlatformCheckIndex && composeUpIndex > loadedBackendPlatformCheckIndex, 'Both loaded target images must be executed without pulling before Compose changes state');
+assert(runningTimeCheckIndex > composeUpIndex, 'Running container CST time must be checked after Compose health wait');
 const frontendImageTimeIndex = deploy.indexOf('  assert_image_cst_time "$frontend_image"');
 const firstImageSaveIndex = deploy.indexOf('  docker save -o "$package_root/frontend-image.tar"');
 assert(frontendImageTimeIndex >= 0 && firstImageSaveIndex > frontendImageTimeIndex, 'Built image CST time must be checked before Docker save');
@@ -130,6 +138,9 @@ assert(compose.includes('"${DOCKER_BIND_IP}:${FRONTEND_PORT}:${FRONTEND_PORT}"')
 assert(compose.includes('"${DOCKER_BIND_IP}:${BACKEND_PORT}:${BACKEND_PORT}"'), 'Backend port mapping is invalid');
 assert(compose.includes('VITE_API_BASE_URL: "${VITE_API_BASE_URL:?VITE_API_BASE_URL is required}"'), 'Frontend API path is not passed to Nginx');
 assert(compose.includes('BACKEND_PORT: "${BACKEND_PORT:?BACKEND_PORT is required}"'), 'Backend port is not passed to Nginx');
+assert(compose.includes('BACKEND_URL: "${BACKEND_URL:?BACKEND_URL is required}"'), 'Backend URL is not passed to the backend with its contract name');
+assert((compose.match(/BACKEND_PORT: "\$\{BACKEND_PORT:\?BACKEND_PORT is required\}"/g) ?? []).length === 2, 'BACKEND_PORT must be passed to both frontend Nginx and backend with its contract name');
+assert(!/^\s+(?:HOST|PORT):/m.test(compose), 'Legacy backend HOST or PORT environment mapping is forbidden');
 assert(compose.includes('NGINX_ENVSUBST_FILTER: "^(FRONTEND_URL|FRONTEND_PORT|VITE_API_BASE_URL|BACKEND_PORT)$"'), 'Nginx envsubst filter does not cover the runtime API proxy');
 assert(!/\b(?:postgres|database|db):\s*$|postgres:\d|DATABASE_MIGRATION|MIGRATIONS_SOURCE|RELEASE_VERSION|blue|green/i.test(compose), 'Compose contains a database, migration, release or blue-green configuration');
 
@@ -157,6 +168,11 @@ async function assertImageArchive(name, expectedTag) {
   const { stdout: configText } = await run('tar', ['-xOf', archive, parsed[0].Config], { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024 });
   const config = JSON.parse(configText);
   assert(`${config.os}/${config.architecture}` === env.get('DOCKER_PLATFORM'), `${name} platform must equal DOCKER_PLATFORM`);
+  if (name === 'backend-image.tar') {
+    const imageEnv = config.config?.Env ?? [];
+    assert(Array.isArray(imageEnv), 'backend-image.tar environment metadata is invalid');
+    assert(!imageEnv.some((entry) => /^(?:HOST|PORT)=/.test(entry)), 'backend-image.tar must not contain legacy HOST or PORT environment variables');
+  }
 }
 await assertImageArchive('frontend-image.tar', `${env.get('PROJECT_NAME')}_frontend:latest`);
 await assertImageArchive('backend-image.tar', `${env.get('PROJECT_NAME')}_backend:latest`);

package/.well-known/skills/wdyy-deployment-standard/scripts/validate-deployment-package.test.mjs

@@ -92,6 +92,15 @@ if (args[0] === 'build') {
   process.exit(0);
 }
 if (args[0] === 'run') {
+  const entrypointIndex = args.indexOf('--entrypoint');
+  if (entrypointIndex >= 0 && args[entrypointIndex + 1] === 'uname') {
+    const image = args[entrypointIndex + 2];
+    if (process.env.MISSING_PLATFORM_IMAGE === image) process.exit(1);
+    const configuredPlatform = process.env.IMAGE_PLATFORM || 'linux/amd64';
+    const machine = process.env.IMAGE_MACHINE || (configuredPlatform === 'linux/arm64' ? 'aarch64' : 'x86_64');
+    process.stdout.write(machine + '\\n');
+    process.exit(0);
+  }
   const image = args[args.indexOf('-c') - 1];
   if (process.env.FAIL_IMAGE_TIME && image.includes(process.env.FAIL_IMAGE_TIME)) process.exit(1);
   process.stdout.write((process.env.IMAGE_TIME || '19 CST +0800') + '\\n');
@@ -205,6 +214,18 @@ async function rewriteImageArchivePlatform(archive, platform) {
   await run('tar', ['-cf', archive, '-C', temporary, 'manifest.json', configName]);
 }
 
+async function rewriteBackendImageEnv(archive, imageEnv) {
+  const temporary = await mkdtemp(join(tmpdir(), 'wdyy-image-env-'));
+  created.push(temporary);
+  await run('tar', ['-xf', archive, '-C', temporary]);
+  const manifest = JSON.parse(await readFile(join(temporary, 'manifest.json'), 'utf8'));
+  const configName = manifest[0].Config;
+  const config = JSON.parse(await readFile(join(temporary, configName), 'utf8'));
+  config.config = { ...(config.config ?? {}), Env: imageEnv };
+  await writeFile(join(temporary, configName), `${JSON.stringify(config)}\n`);
+  await run('tar', ['-cf', archive, '-C', temporary, 'manifest.json', configName]);
+}
+
 test.after(async () => {
   await Promise.all(created.map((path) => rm(path, { recursive: true, force: true })));
 });
@@ -228,12 +249,16 @@ test('build 使用本地基础镜像并生成一个含双镜像归档的压缩
   assert.match(compose, /container_name: "\$\{PROJECT_NAME:\?PROJECT_NAME is required\}_frontend"/);
   assert.match(compose, /container_name: "\$\{PROJECT_NAME:\?PROJECT_NAME is required\}_backend"/);
   assert.equal((compose.match(/restart: unless-stopped/g) ?? []).length, 2);
+  assert.match(compose, /BACKEND_URL: "\$\{BACKEND_URL:\?BACKEND_URL is required\}"/);
+  assert.equal((compose.match(/BACKEND_PORT: "\$\{BACKEND_PORT:\?BACKEND_PORT is required\}"/g) ?? []).length, 2);
+  assert.doesNotMatch(compose, /^\s+(?:HOST|PORT):/m);
   const log = await readFile(item.log, 'utf8');
   assert.match(log, /image inspect nginx:stable/);
   assert.match(log, /image inspect node:24-bookworm-slim/);
   assert.equal((log.match(/build --pull=false --platform linux\/amd64/g) ?? []).length, 2);
   assert.match(log, /build --pull=false --platform linux\/amd64 .*--build-arg VITE_API_BASE_URL=\/api .*example_project_frontend:latest/);
-  assert.equal((log.match(/^run --rm --pull=never --platform linux\/amd64 /gm) ?? []).length, 2);
+  assert.equal((log.match(/^run --rm --pull=never --platform linux\/amd64 --entrypoint uname /gm) ?? []).length, 4);
+  assert.equal((log.match(/^run --rm --pull=never --platform linux\/amd64 --entrypoint sh /gm) ?? []).length, 2);
   assert.doesNotMatch(log, /(^|\s)pull(\s|$)/m);
   assert.match(log, /save -o .*frontend-image\.tar example_project_frontend:latest/);
   assert.match(log, /save -o .*backend-image\.tar example_project_backend:latest/);
@@ -241,12 +266,29 @@ test('build 使用本地基础镜像并生成一个含双镜像归档的压缩
 
 test('基础镜像平台不匹配时在 build 前失败', async () => {
   const item = await fixture();
-  await assert.rejects(buildProject(item, { IMAGE_PLATFORM: 'linux/arm64' }), /image platform mismatch for nginx:stable: expected linux\/amd64, got linux\/arm64/);
+  await assert.rejects(buildProject(item, { IMAGE_MACHINE: 'aarch64' }), /image platform mismatch for nginx:stable: expected linux\/amd64 \(x86_64\), got aarch64/);
   const log = await readFile(item.log, 'utf8');
   assert.doesNotMatch(log, /^build /m);
   assert.equal((await readdir(join(item.root, 'deploy'))).length, 0);
 });
 
+test('多平台索引默认元数据不同但目标子镜像可运行时继续构建', async () => {
+  const item = await fixture();
+  const result = await buildProject(item, { INSPECT_PLATFORM: 'linux/arm64', IMAGE_PLATFORM: 'linux/amd64', IMAGE_MACHINE: 'x86_64' });
+  assert.match(result.stdout, /delivery archive created/);
+  const log = await readFile(item.log, 'utf8');
+  assert.doesNotMatch(log, /image inspect --platform/);
+  assert.match(log, /^run --rm --pull=never --platform linux\/amd64 --entrypoint uname nginx:stable -m$/m);
+});
+
+test('目标平台子镜像缺失时在 build 前失败且不拉取', async () => {
+  const item = await fixture();
+  await assert.rejects(buildProject(item, { MISSING_PLATFORM_IMAGE: 'nginx:stable' }), /image platform is unavailable for nginx:stable: linux\/amd64/);
+  const log = await readFile(item.log, 'utf8');
+  assert.doesNotMatch(log, /^build /m);
+  assert.doesNotMatch(log, /(^|\s)pull(\s|$)/m);
+});
+
 test('macOS arm64 与 Windows WSL2 使用 Linux engine 生成并部署单架构交付包', async () => {
   const item = await fixture();
   await setTargetPlatform(item.root, 'linux/arm64');
@@ -322,6 +364,44 @@ test('服务器无参数执行时从脚本目录整体加载并部署前后端',
   assert.match(await readFile(join(extracted, 'logs/deploy.log'), 'utf8'), /CST \+0800 operation=deploy result=success/);
 });
 
+test('macOS arm64 Docker Desktop 可加载并运行 linux/amd64 交付包', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await writeFile(item.log, '');
+  await run(join(extracted, 'deploy.sh'), [], {
+    env: { ...item.environment, HOST_KERNEL: 'Darwin', SERVER_PLATFORM: 'linux/arm64', IMAGE_PLATFORM: 'linux/amd64', IMAGE_MACHINE: 'x86_64' },
+  });
+  const log = await readFile(item.log, 'utf8');
+  const secondLoadIndex = log.lastIndexOf('load -i ');
+  const frontendProbeIndex = log.indexOf('run --rm --pull=never --platform linux/amd64 --entrypoint uname example_project_frontend:latest -m', secondLoadIndex);
+  const backendProbeIndex = log.indexOf('run --rm --pull=never --platform linux/amd64 --entrypoint uname example_project_backend:latest -m', frontendProbeIndex);
+  const composeIndex = log.indexOf('compose --env-file ', backendProbeIndex);
+  assert(secondLoadIndex >= 0 && frontendProbeIndex > secondLoadIndex && backendProbeIndex > frontendProbeIndex && composeIndex > backendProbeIndex);
+  assert.match(log, /compose .* up -d --force-recreate --no-build --pull never --wait frontend backend/);
+  assert.doesNotMatch(log, /(^|\s)pull(\s|$)/m);
+});
+
+test('macOS arm64 的 amd64 目标镜像探针失败时不启动 Compose', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await writeFile(item.log, '');
+  await assert.rejects(run(join(extracted, 'deploy.sh'), [], {
+    env: {
+      ...item.environment,
+      HOST_KERNEL: 'Darwin',
+      SERVER_PLATFORM: 'linux/arm64',
+      IMAGE_PLATFORM: 'linux/amd64',
+      MISSING_PLATFORM_IMAGE: 'example_project_frontend:latest',
+    },
+  }), /image platform is unavailable for example_project_frontend:latest: linux\/amd64/);
+  const log = await readFile(item.log, 'utf8');
+  assert.equal((log.match(/^load -i /gm) ?? []).length, 2);
+  assert.doesNotMatch(log, /^compose .* up /m);
+  assert.doesNotMatch(log, /(^|\s)pull(\s|$)/m);
+});
+
 test('服务器平台无法读取、不受支持或不匹配时在加载镜像前失败', async () => {
   const item = await fixture();
   await buildProject(item);
@@ -329,9 +409,14 @@ test('服务器平台无法读取、不受支持或不匹配时在加载镜像
     [{ FAIL_SERVER_PLATFORM_READ: '1' }, /Docker Server platform is unavailable/],
     [{ SERVER_PLATFORM: 'windows/amd64' }, /Windows container mode is unsupported; switch Docker Desktop to Linux containers/],
     [{ SERVER_PLATFORM: 'linux/arm64' }, /Docker Server platform mismatch: expected linux\/amd64, got linux\/arm64/],
+    [{ HOST_KERNEL: 'Darwin', SERVER_PLATFORM: 'linux/amd64', IMAGE_PLATFORM: 'linux/arm64' }, /Docker Server platform mismatch: expected linux\/arm64, got linux\/amd64/],
   ];
   for (const [extraEnvironment, expectedError] of cases) {
     const extracted = await extractArchive(item);
+    if (extraEnvironment.IMAGE_PLATFORM === 'linux/arm64') {
+      await setTargetPlatform(extracted, 'linux/arm64');
+      await rewriteManifest(extracted);
+    }
     await writeFile(item.log, '');
     await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: { ...item.environment, ...extraEnvironment } }), expectedError);
     const log = await readFile(item.log, 'utf8');
@@ -477,6 +562,26 @@ test('validator 拒绝容器名、重启策略或端口单一来源被破坏', a
   await assert.rejects(run(process.execPath, [validator, portPackage]), /Frontend port mapping is invalid/);
 });
 
+test('validator 拒绝后端监听变量缺失或映射为旧名称', async () => {
+  const item = await fixture();
+  await buildProject(item);
+
+  const missingUrlPackage = await extractArchive(item);
+  let compose = await readFile(join(missingUrlPackage, 'docker-compose.yml'), 'utf8');
+  await writeFile(join(missingUrlPackage, 'docker-compose.yml'), compose.replace('      BACKEND_URL: "${BACKEND_URL:?BACKEND_URL is required}"\n', ''));
+  await rewriteManifest(missingUrlPackage);
+  await assert.rejects(run(process.execPath, [validator, missingUrlPackage]), /Backend URL is not passed to the backend with its contract name/);
+
+  const legacyPackage = await extractArchive(item);
+  compose = await readFile(join(legacyPackage, 'docker-compose.yml'), 'utf8');
+  compose = compose
+    .replace('      BACKEND_URL: "${BACKEND_URL:?BACKEND_URL is required}"', '      HOST: "${BACKEND_URL}"')
+    .replace('      BACKEND_PORT: "${BACKEND_PORT:?BACKEND_PORT is required}"\n      TZ:', '      PORT: "${BACKEND_PORT}"\n      TZ:');
+  await writeFile(join(legacyPackage, 'docker-compose.yml'), compose);
+  await rewriteManifest(legacyPackage);
+  await assert.rejects(run(process.execPath, [validator, legacyPackage]), /Backend URL is not passed|BACKEND_PORT must be passed|Legacy backend HOST or PORT/);
+});
+
 test('validator 拒绝冲突的 API 路径和缺失的代理注入', async () => {
   const item = await fixture();
   await buildProject(item);
@@ -513,6 +618,15 @@ test('validator 拒绝镜像归档平台与 DOCKER_PLATFORM 不一致', async ()
   await assert.rejects(run(process.execPath, [validator, extracted]), /backend-image\.tar platform must equal DOCKER_PLATFORM/);
 });
 
+test('validator 拒绝后端镜像包含旧 HOST 或 PORT 环境变量', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await rewriteBackendImageEnv(join(extracted, 'backend-image.tar'), ['NODE_ENV=production', 'PORT=3000']);
+  await rewriteManifest(extracted);
+  await assert.rejects(run(process.execPath, [validator, extracted]), /backend-image\.tar must not contain legacy HOST or PORT environment variables/);
+});
+
 test('build 在任何 Docker 操作前拒绝环境文件命令语法', async () => {
   const item = await fixture();
   await writeFile(join(item.root, '.env'), envText.replace('DB_PASSWORD=secret', 'DB_PASSWORD=$(id)'), { mode: 0o600 });

package/.well-known/skills/wdyy-deployment-standard/templates/backend.Dockerfile.template

@@ -10,7 +10,6 @@ FROM ${BACKEND_BASE_IMAGE} AS runtime
 WORKDIR /app
 ARG BACKEND_PORT
 ENV NODE_ENV=production
-ENV PORT=${BACKEND_PORT}
 LABEL org.opencontainers.image.title="wdyy-backend"
 COPY --from=build /runtime ./src/backend/
 EXPOSE ${BACKEND_PORT}

package/.well-known/skills/wdyy-deployment-standard/templates/deploy.sh.template

@@ -8,6 +8,7 @@ STAGING_ROOT=
 DEPLOY_ROOT=
 OPERATION=
 CHECKSUM_TOOL=
+EXECUTION_KERNEL=
 
 fail() {
   echo "$*" >&2
@@ -63,6 +64,7 @@ assert_execution_host() {
   if [[ "$kernel" == Linux ]] && { [[ -n "${WSL_DISTRO_NAME:-}" ]] || grep -qi microsoft /proc/sys/kernel/osrelease 2>/dev/null; }; then
     [[ ! "$SCRIPT_DIR" =~ ^/mnt/[A-Za-z](/|$) ]] || fail "Windows Docker Desktop execution must use the WSL2 Linux filesystem, not $SCRIPT_DIR"
   fi
+  EXECUTION_KERNEL="$kernel"
 }
 
 reset_configuration() {
@@ -140,9 +142,19 @@ validate_configuration() {
 }
 
 assert_image_platform() {
-  local image="$1" actual
-  actual="$(docker image inspect --platform "$DOCKER_PLATFORM" --format '{{.Os}}/{{.Architecture}}' "$image" 2>/dev/null)" || fail "image platform is unavailable for $image: $DOCKER_PLATFORM"
-  [[ "$actual" == "$DOCKER_PLATFORM" ]] || fail "image platform mismatch for $image: expected $DOCKER_PLATFORM, got $actual"
+  local image="$1" actual expected
+  actual="$(docker run --rm --pull=never --platform "$DOCKER_PLATFORM" --entrypoint uname "$image" -m 2>/dev/null)" || fail "image platform is unavailable for $image: $DOCKER_PLATFORM"
+  actual="${actual%$'\r'}"
+  case "$DOCKER_PLATFORM" in
+    linux/amd64)
+      expected=x86_64
+      [[ "$actual" == "$expected" ]] || fail "image platform mismatch for $image: expected $DOCKER_PLATFORM ($expected), got ${actual:-empty}"
+      ;;
+    linux/arm64)
+      expected='aarch64 or arm64'
+      [[ "$actual" == aarch64 || "$actual" == arm64 ]] || fail "image platform mismatch for $image: expected $DOCKER_PLATFORM ($expected), got ${actual:-empty}"
+      ;;
+  esac
 }
 
 assert_server_platform() {
@@ -151,7 +163,11 @@ assert_server_platform() {
   [[ -n "$actual" ]] || fail "Docker Server platform is empty"
   [[ "$actual" != windows/* ]] || fail "Windows container mode is unsupported; switch Docker Desktop to Linux containers"
   [[ "$actual" =~ ^linux/(amd64|arm64)$ ]] || fail "unsupported Docker Server platform: $actual"
-  [[ "$actual" == "$DOCKER_PLATFORM" ]] || fail "Docker Server platform mismatch: expected $DOCKER_PLATFORM, got $actual"
+  [[ "$actual" == "$DOCKER_PLATFORM" ]] && return 0
+  if [[ "$EXECUTION_KERNEL" == Darwin && "$actual" == linux/arm64 && "$DOCKER_PLATFORM" == linux/amd64 ]]; then
+    return 0
+  fi
+  fail "Docker Server platform mismatch: expected $DOCKER_PLATFORM, got $actual; only macOS with linux/arm64 Docker Server may run linux/amd64 through verified emulation"
 }
 
 assert_container_ownership() {

package/.well-known/skills/wdyy-deployment-standard/templates/docker-compose.yml

@@ -29,8 +29,8 @@ services:
     platform: "${DOCKER_PLATFORM:?DOCKER_PLATFORM is required}"
     env_file: ./.env
     environment:
-      HOST: "${BACKEND_URL}"
-      PORT: "${BACKEND_PORT}"
+      BACKEND_URL: "${BACKEND_URL:?BACKEND_URL is required}"
+      BACKEND_PORT: "${BACKEND_PORT:?BACKEND_PORT is required}"
       TZ: "${TZ:?TZ is required}"
     ports:
       - "${DOCKER_BIND_IP}:${BACKEND_PORT}:${BACKEND_PORT}"
@@ -38,7 +38,7 @@ services:
       - ./logs:/app/logs
     restart: unless-stopped
     healthcheck:
-      test: ["CMD-SHELL", "node -e \"const http=require('http');const r=http.get({host:'127.0.0.1',port:process.env.BACKEND_PORT,path:'/health'},x=>process.exit(x.statusCode===200?0:1));r.on('error',()=>process.exit(1));r.setTimeout(2500,()=>{r.destroy();process.exit(1)})\""]
+      test: ["CMD-SHELL", "node -e \"const http=require('http');const r=http.get({host:'127.0.0.1',port:process.env.BACKEND_PORT,path:'/${API_PREFIX}/health'},x=>process.exit(x.statusCode===200?0:1));r.on('error',()=>process.exit(1));r.setTimeout(2500,()=>{r.destroy();process.exit(1)})\""]
       interval: 10s
       timeout: 3s
       retries: 6

package/.well-known/skills/wdyy-logging-standard/SKILL.md

@@ -26,7 +26,7 @@ description: 为 NestJS 和 Vue 项目实现仅写入项目根目录 ./logs 的
 ## 执行步骤
 
 1. 定义 `timestamp`、`level`、`service`、`instanceId`、`env`、`traceId`、`userId`、`method`、`path`、`query`、`body`、`response`、`statusCode`、`result`、`durationMs`、`errorCode`、`message`、`params` 的最小 JSON 契约。`timestamp` 必须为服务器本地时间 `YYYY-MM-DD HH:mm:ss`，精确到秒。
-2. 在入口生成或透传 traceId；在内部 REST 调用中继续传递。
+2. 在入口生成或透传 traceId；在内部 REST 调用中继续传递。Vue 的 Axios 请求拦截器生成 `x-trace-id` 时，优先调用 `crypto.randomUUID()`；HTTP IP 等非安全上下文中该 API 不可用时，必须降级为“时间戳 + 随机数”生成的非空 traceId，且生成过程不得抛异常或阻断任何请求（包括登录）。可复用实现见 [前端异常上报模板](templates/frontend-error-report.template.ts)。
 3. 统一封装 logger；业务代码不得直接使用 `console.log`。
 4. HTTP 请求日志记录完整的原始 `query`（查询参数）和 `body`（请求体）；授权请求可记录实际用户、模式、表和权限等入参。服务端返回成功时记录 `result: success`；返回失败时记录 `result: failure`，并在 `response` 中记录完整失败内容。HTTP `statusCode` 为 100–399 时为成功，400–599 时为失败。
 5. 日志不执行脱敏、数组截断或大对象裁剪；`body` 必须保留完整原始入参。
@@ -43,12 +43,14 @@ description: 为 NestJS 和 Vue 项目实现仅写入项目根目录 ./logs 的
 
 - 业务代码直接调用 console，或 `body` 未保留完整原始入参。
 - 请求日志缺失 traceId、状态码或耗时。
+- 前端仅调用 `crypto.randomUUID()`，使非安全 HTTP 上下文的请求在发送前失败。
 - 日志路径可被环境变量改变、生成了日志子目录、同秒文件覆盖既有文件，或前端异常未进入统一后端日志。
 
 ## Verification
 
 - [ ] 正常、异常和 HTTP 请求日志均为可解析 JSON。
 - [ ] traceId 跨入口与内部调用可追踪。
+- [ ] 在 HTTPS 与 HTTP 非安全上下文中，Axios 均能为请求写入非空 `x-trace-id`；登录及其他 API 请求不会因 traceId 生成失败而中断。
 - [ ] 完整 HTTP 入参、服务端成功/失败结果映射、失败响应内容、固定 `./logs` 路径、同秒递增命名与轮转阈值均有测试覆盖。
 - [ ] 前端异常上报经过后端身份校验。
 - [ ] 日志直接写入项目根目录 `./logs`，且容器替换后日志仍保留。

package/.well-known/skills/wdyy-logging-standard/reference/logging-rules.md

@@ -8,6 +8,7 @@
 - 日志仅记录关键业务事件、请求和异常；`params`、`query`、`body` 和 `response` 均保留完整原始值，不执行脱敏、数组截断或大对象裁剪。授权请求可记录实际用户、模式、表和权限等入参。
 - HTTP 日志必须保留 `statusCode`。服务端成功返回时 `result` 为 `success`；失败返回时 `result` 为 `failure`，并在 `response` 中保留完整失败内容。100–399 为成功，400–599 为失败。
 - HTTP 入口和内部服务调用必须透传 traceId。
+- Vue Axios 请求拦截器必须为每个请求写入非空 `x-trace-id`。优先使用 `globalThis.crypto?.randomUUID()`；若其不存在或不可调用（例如通过 HTTP IP 地址访问的非安全上下文），使用时间戳加随机数生成 traceId。降级仅用于请求追踪，不可将其视为加密随机值；生成逻辑不得抛异常或阻止登录、仪表盘、患者管理等 API 请求发出。
 - 每条日志必须包含 `instanceId`；所有进程共享同一 `./logs`，通过排他创建和同秒递增后缀避免覆盖。
 - Vue 未处理异常和 Promise 拒绝必须上报后端；后端校验请求身份后写入统一日志。
 - 容器必须将宿主机项目根目录 `./logs` 挂载到应用根目录 `/app/logs`，替换容器不得删除历史日志。

package/.well-known/skills/wdyy-logging-standard/templates/frontend-error-report.template.ts

@@ -6,6 +6,25 @@ type FrontendErrorReport = {
   occurredAt: string;
 };
 
+/**
+ * 为 HTTP 请求生成追踪标识。HTTP 非安全上下文可能不提供 crypto.randomUUID，
+ * 因此追踪标识必须有非加密用途的回退实现，不能阻断请求。
+ */
+export function createTraceId(): string {
+  const cryptoApi = globalThis.crypto;
+  if (typeof cryptoApi?.randomUUID === 'function') {
+    return cryptoApi.randomUUID();
+  }
+
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+// Axios 请求拦截器示例：
+// api.interceptors.request.use((config) => {
+//   config.headers.set('x-trace-id', createTraceId());
+//   return config;
+// });
+
 export async function reportFrontendError(report: FrontendErrorReport): Promise<void> {
   const response = await fetch('/api/client-errors', {
     method: 'POST',

package/README.md

@@ -43,7 +43,7 @@ wdyy update-skill --all
 
 `wdyy update-skill <skill-name>` 只接受 5 个受管理的 `wdyy-*` Skill，且仅替换系统用户目录 `.agents/skills/` 中的指定目录；`--all` 替换全部 5 个受管理 Skill。两种方式都不会写入调用项目的 `AGENTS.md`、`AGENTS_new.md`、`docs/bug_record.md` 或 `.agents/skills/`，也不会执行 `openspec init`。首次初始化或需要重新生成项目规则时，使用 `wdyy init`。
 
-部署 Skill 生成的标准流程为：在 Linux、macOS Docker Desktop，或 Windows Docker Desktop + WSL2/Linux 文件系统的项目根目录执行 `./deploy.sh build`，只使用本地已有的 Node、Nginx 基础镜像构建 `<项目名>_frontend:latest` 与 `<项目名>_backend:latest`，分别导出两个镜像 tar，并统一封装为 `deploy/<项目名>-docker.tar.gz`。工程师人工复制并解压该压缩包，在平台匹配的 Linux engine 上无参数执行 `./deploy.sh` 即校验、加载并整体部署前后端；另可执行 `./deploy.sh stop` 和 `./deploy.sh status`。数据库通过 `.env` 直连远程 PostgreSQL，不生成数据库容器；前后端的宿主机与容器端口都来自 `.env`，容器名与镜像 repository 相同，使用 `unless-stopped`，并验证 24 小时制 CST（UTC+8）；日志直接保存在部署根 `logs/`。不支持原生 PowerShell 或 Windows 容器模式。
+部署 Skill 生成的标准流程为：在 Linux、macOS Docker Desktop，或 Windows Docker Desktop + WSL2/Linux 文件系统的项目根目录执行 `./deploy.sh build`，只使用本地已有的 Node、Nginx 基础镜像构建 `<项目名>_frontend:latest` 与 `<项目名>_backend:latest`，分别导出两个镜像 tar，并统一封装为 `deploy/<项目名>-docker.tar.gz`。工程师人工复制并解压该压缩包，在受支持的 Linux engine 上无参数执行 `./deploy.sh` 即校验、加载并整体部署前后端；macOS/arm64 Docker Desktop 可通过禁止拉取的实际目标镜像探针验证并运行 `linux/amd64` 包，而不是仅按 Server 原生架构拒绝。另可执行 `./deploy.sh stop` 和 `./deploy.sh status`。数据库通过 `.env` 直连远程 PostgreSQL，不生成数据库容器；前后端的宿主机与容器端口都来自 `.env`，容器名与镜像 repository 相同，使用 `unless-stopped`，并验证 24 小时制 CST（UTC+8）；日志直接保存在部署根 `logs/`。不支持原生 PowerShell 或 Windows 容器模式。
 
 中大型变更先使用 `/opsx:explore` 或 `/opsx:propose <change-name>`，在方案确认后使用 `/opsx:apply`；完成验证后使用 `/opsx:archive`。涉及数据库、内部 API、日志、部署时，按 `AGENTS.md` 的路由加载相应企业 Skill。所有 URL、端口和 IP 地址从 `.env` 读取，不得硬编码；所有项目管理的日志直接写入项目根目录 `logs/`；生产部署不使用蓝绿发布。不得提交秘密或生产环境 `.env`。项目完成后创建 `README.md`，说明技术栈、目录结构和安装部署。
 
@@ -66,7 +66,7 @@ wdyy update-skill --all
 
 ### 使用发布脚本
 
-推荐从项目根目录手动运行 `release_npm.sh`。脚本会检查工作区、组织权限、lint 与打包内容，自动执行 `npm version <patch|minor|major>`、`npm publish --access public`；发布成功后等待 5 秒，再一次查询刚发布的确切版本进行 registry 核验。它不会执行登录、浏览器认证或处理认证凭据。
+推荐从项目根目录手动运行 `release_npm.sh`。脚本会检查工作区、组织权限、lint 与打包内容，自动执行 `npm version <patch|minor|major>`、`npm publish --access public`；发布成功后等待 15 秒，再一次查询刚发布的确切版本进行 registry 核验。它不会执行登录、浏览器认证或处理认证凭据。
 
 首次运行或登录失效时，先手工登录；脚本检测到未登录也会提示并退出：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdyy/skills",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "企业内部开发 Skill 与项目初始化命令",
   "type": "module",
   "bin": {