@wdyy/skills 0.1.11 → 0.1.13

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

@@ -7,8 +7,8 @@
     },
     {
       "name": "wdyy-deployment-standard",
-      "description": "基于标准五段根 .env，为无 CI/CD 项目生成确定性的前后端双 Docker 发布配置、本地 deploy.sh build 完整打包、人工上传及按独立端口执行蓝绿启动、替换、重启、停止、删除和回滚；部署根由脚本位置确定且不处理数据库迁移。Use when 规划、实现、审查或执行手工生产部署时。",
-      "files": ["SKILL.md", "agents/openai.yaml", "reference/linux-deployment-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/Dockerfile.template", "templates/frontend.Dockerfile.template", "templates/frontend-container.conf.template", "templates/env.example.template", "templates/deploy.sh.template", "templates/docker-compose.blue-green.yml", "templates/dockerignore.template", "templates/nginx-upstream.template.conf"]
+      "description": "为无 CI/CD 的前后端项目生成并验证统一 Docker 交付：使用本地已有基础镜像构建前后端两个独立镜像，分别导出后封装为一个压缩包，数据库直连远程实例，服务器无参数一键部署整个项目栈。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"]
     },
     {
       "name": "wdyy-api-standard",

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

@@ -1,72 +1,47 @@
 ---
 name: wdyy-deployment-standard
-description: 基于标准五段根 .env，为无 CI/CD 项目生成确定性的前后端双 Docker 发布配置、本地 deploy.sh build 完整打包、人工上传及按独立端口执行蓝绿启动、替换、重启、停止、删除和回滚；部署根由脚本位置确定且不处理数据库迁移。Use when 规划、实现、审查或执行手工生产部署时。
+description: 为无 CI/CD 的前后端项目生成并验证统一 Docker 交付：使用本地已有基础镜像构建前后端两个独立镜像，分别导出后封装为一个压缩包，数据库直连远程实例，服务器无参数一键部署整个项目栈。Use when 规划、实现、审查或执行人工 Docker 生产交付时。
 ---
 
-# 企业部署规范
+# 统一 Docker 交付规范
 
 ## Overview
 
-把开发、构建、上传和服务器操作分开：开发只用 `pnpm dev`；本地用 `./deploy.sh build` 生成前后端双镜像和完整 `deploy/`；工程师人工上传；服务器按根 `.env` 的项目端口执行成对蓝绿切流。
+把一个项目作为一个整体交付：本地执行 `./deploy.sh build`，生成前端、后端两个独立镜像并分别导出，最终只产出一个压缩包；工程师人工上传并解压；服务器无参数执行 `./deploy.sh`，一次性加载并部署整个前后端项目栈。
 
-## 使用边界
+## Workflow
 
-1. 先读取目标项目真实的 pnpm scripts、前后端构建输出、健康/版本接口、Dockerfile、`.env` 和 Nginx include 方式。
-2. 完整读取 [Linux 部署规则](reference/linux-deployment-rules.md)，运行 `node scripts/generate-deployment-files.mjs --target <目标项目根目录> --write` 确定性生成受版本控制文件，并向 `.env` 与 `.env.example` 的唯一“部署”段追加同名空配置；既有文件不一致时先审查差异，只有工程师确认后才使用 `--force`。
-3. 应用 URL 与端口只使用 `FRONTEND_URL`、`FRONTEND_PORT`、`BACKEND_URL`、`BACKEND_PORT`；部署端点使用各自唯一变量。健康和版本 URL 在脚本中由主机、端口及固定路径构造，不在 `.env` 中重复配置。
-4. 工程师人工上传 `deploy/` 全部内容；脚本不得上传、拉取代码、安装依赖、修改共享 Nginx 主配置或替代 GO/NO-GO。
-5. 生成后先运行生成器的 `--check`，再运行 `scripts/validate-deployment-package.mjs` 和全部行为测试。
+1. 读取目标项目真实的 pnpm scripts、前后端构建输出、Dockerfile、健康检查、根 `.env` 和远程数据库连接方式。
+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` 和行为测试。
+5. 本地执行 `./deploy.sh build`；只在全部校验成功后原子替换 `deploy/<PROJECT_NAME>-docker.tar.gz`。
+6. 人工上传并解压压缩包，在服务器解压目录无参数执行 `./deploy.sh`。
 
-## 固定契约
+## Fixed Contract
 
-- 项目名只允许小写字母、数字和下划线；服务器部署根由上传后的 `deploy.sh` 物理路径确定。
-- 两个镜像必须精确命名为 `<项目名称>_frontend:<YYYYMMDD-NNN>` 和 `<项目名称>_backend:<YYYYMMDD-NNN>`。
-- Compose 必须包含 frontend-blue、backend-blue、frontend-green、backend-green；同一颜色的前后端作为一个切流单元。
-- 宿主机 Nginx 只监听根 `.env` 的 `PROJECT_HTTP_PORT`，`/api/` 代理活动后端，其他请求代理活动前端。
-- 所有容器只把项目根 `./logs` 挂载到 `/app/logs`；日志文件直接位于 `logs/`，不得创建服务、颜色或日期子目录。
-- 根 `.env` 原样复制到 `deploy/.env` 并人工上传，但必须被 `.dockerignore` 排除，且不得进入版本目录或任一镜像。
-- `.env.example` 是环境主模板，内置 `FRONTEND_BASE_IMAGE=nginx:stable` 与 `BACKEND_BASE_IMAGE=node:24-alpine3.24`；`.env` 可在生成后显式覆盖。相同标签在不同时间重新构建时可能对应不同基础镜像内容，但已导出的项目成品镜像仍按版本确定部署。
-- 环境文件固定按“前端、后端、数据库、API、部署”排列；部署生成器保留前四段和已有值，只扩充部署段。
-- 发布链路不接受数据库迁移参数，也不打包、校验或执行迁移文件。
-- 相同输入生成的 deploy.sh、Compose、Nginx 配置必须字节一致；版本指针、镜像归档和 manifest 可随发布变化。
+- 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest` 两个独立镜像。
+- 分别导出 `frontend-image.tar`、`backend-image.tar`，但只交付一个 `<PROJECT_NAME>-docker.tar.gz`。
+- 构建前检查 `FRONTEND_BASE_IMAGE`、`BACKEND_BASE_IMAGE` 已存在于本地；缺失即失败，不执行 `docker pull`。
+- Compose 只定义 frontend、backend；数据库通过 `.env` 直连远程实例，不生成数据库容器、数据卷或迁移路径。
+- 服务器无参数命令整体部署；只额外允许 `stop` 和 `status`，不得独立操作单一服务。
+- 前后端直接暴露 `.env` 指定的宿主机端口；两个容器共同挂载项目根 `./logs` 到 `/app/logs`。
+- `.env` 可以进入人工上传的压缩包，但必须被 `.dockerignore` 排除，不得进入镜像。
 
-## 工作流
+## Prohibited
 
-1. 使用 `pnpm dev` 完成开发测试。
-2. 执行不带额外参数的 `./deploy.sh build`；从 `AGENTS.md` 唯一“发布记录”表生成 `YYYYMMDD-NNN`。
-3. 依次通过测试、lint、类型检查、构建、双镜像语义检查、包校验和配置确定性检查；成功后才替换 `deploy/` 并写发布记录。
-4. 人工把 `deploy/` 全部内容上传到目标部署目录；生产值不得通过命令行传入。
-5. 首次部署执行 `./deploy.sh start`；后续新版本执行 `./deploy.sh replace`。
-6. 通过 `restart`、`stop`、`status`、`rollback <version>` 管理当前项目；`remove` 只删除本项目容器、网络及两个精确镜像仓库。
-
-## Nginx 当前项目边界
-
-- 每个项目只写自身 `nginx/site.conf` 和 `nginx/active-upstreams.conf`。
-- upstream 名称由严格项目名确定，不接受自由文本配置。
-- 安装候选配置后运行 `nginx -t` 和 reload；失败时恢复本项目旧文件。
-- 不扫描、校验或修改其他项目配置、端口或 Nginx include。
-
-## 禁止事项
-
-- 不得接受人工 build/start/replace 版本参数，不得扫描目录替代发布账本或 `release.env`。
-- 不得使用 Bash `source`/`eval` 解析 `.env` 或状态文件。
-- 不得使用镜像 fallback、固定 `/srv`、固定 URL/IP/端口、PM2、systemd 或自动安装。
-- 不得重新引入 `FRONTEND_CONTAINER_PORT`、`BACKEND_CONTAINER_PORT`、`BACKEND_LISTEN_HOST` 或任何可推导的 `*_HEALTH_URL`、`*_VERSION_URL`。
-- 不得先停止活动颜色再启动新颜色，不得分别切换前后端，不得在验证前 reload。
-- 不得自动执行 psql、迁移脚本或数据库回滚。
-- 不得让 `remove` 删除其他项目资源、日志、发布文件、状态或 Nginx 配置。
-- 不得以字符串关键字存在代替命令行为、失败恢复和资源边界测试。
+- 不得使用镜像仓库 pull、镜像 fallback、数据库容器、数据库迁移、宿主机 Nginx、蓝绿、滚动切流或自动回滚。
+- 不得保留发布账本、版本目录、`release.env`、交互菜单或前后端独立替换命令。
+- 不得上传文件、拉取代码、安装 Docker、固定服务器目录或使用 `source`、`eval` 执行 `.env`。
+- 不得跳过清单、镜像标签、Compose 服务范围、远程数据库配置或健康状态验证。
 
 ## Verification
 
-- [ ] 两个镜像名称、标签和版本 label 精确匹配发布版本。
-- [ ] 四个服务均使用根 `.env`，且只挂载 `../../logs:/app/logs`。
-- [ ] `.env` 与 `.env.example` 的五段、变量顺序一致，部署段键相同且无重复 URL/端口配置。
-- [ ] 外部项目端口唯一；Nginx 一次同时切换前后端，失败恢复旧流量和状态。
-- [ ] start、replace、restart、stop、remove、status、rollback 行为与资源范围均通过测试。
-- [ ] 不存在数据库迁移参数、迁移包内容或数据库执行路径。
-- [ ] 连续两次构建的配置文件一致，失败不写发布记录、不暴露半成品。
-- [ ] `deploy/` 含根 `.env`，但版本目录、Docker 上下文和镜像不含秘密文件。
-- [ ] 替换或删除容器后，项目根 `logs/` 内容仍保留。
+- [ ] deploy 目录只有一个 `<PROJECT_NAME>-docker.tar.gz`。
+- [ ] 压缩包解压后只含 `.env`、deploy.sh、docker-compose.yml、两个镜像 tar 和 manifest.sha256。
+- [ ] 两个镜像归档各自只含预期的 `latest` 标签。
+- [ ] 构建与服务器 Compose 均禁止 pull，服务器禁止 build。
+- [ ] Compose 只含 frontend、backend，并使用远程数据库环境变量和根 logs。
+- [ ] 无参数部署、stop、status 的实际行为及失败传播通过测试。
 
-任一步失败必须明确报告具体阶段并保持或恢复本项目原流量；不得以兜底、静默跳过、强制切流或删除失败证据规避问题。
+任一步失败必须指出具体阶段并返回非零；不得静默跳过、伪造成功或删除上一份成功交付包。

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "wdyy-deployment-standard"
-  short_description: "Build isolated dual-image manual deployment packages"
-  default_prompt: "Use $wdyy-deployment-standard to generate and validate an isolated dual-image manual deployment workflow."
+  short_description: "统一前后端 Docker 双镜像打包与一键整栈部署"
+  default_prompt: "Use $wdyy-deployment-standard to build two local-only Docker images, package them together, and deploy the full stack in one command."

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

@@ -0,0 +1,103 @@
+# 统一 Docker 交付规则
+
+## 1. 生成文件
+
+目标项目维护以下受版本控制文件：
+
+```text
+deploy.sh
+.dockerignore
+src/frontend/Dockerfile
+src/backend/Dockerfile
+scripts/deployment/docker-compose.yml
+scripts/deployment/frontend-container.conf.template
+.env.example
+```
+
+使用 `scripts/generate-deployment-files.mjs --target <project-root> --write` 从 Skill templates 原子生成。现有文件与模板不一致时默认失败；工程师确认差异后才使用 `--force`。生成后必须执行 `--check`。
+
+## 2. 环境配置
+
+根 `.env` 是构建、压缩包和服务器 Compose 的唯一配置源，固定按“前端、后端、数据库、API、部署”排列。部署必须具有非空值：
+
+```dotenv
+FRONTEND_URL=0.0.0.0
+FRONTEND_PORT=5173
+BACKEND_URL=0.0.0.0
+BACKEND_PORT=3000
+DB_URL=database.example.internal
+DB_PORT=5432
+DB_USER=app_user
+DB_PASSWORD=change_me
+DB_NAME=app
+DB_SCHEMA=public
+PROJECT_NAME=example_project
+DOCKER_BIND_IP=0.0.0.0
+FRONTEND_BASE_IMAGE=nginx:stable
+BACKEND_BASE_IMAGE=node:24-alpine3.24
+```
+
+- `PROJECT_NAME` 只允许小写字母开头，后续使用小写字母、数字或下划线。
+- 前后端端口必须不同且位于 1–65535；`DB_PORT` 必须位于 1–65535。
+- `.env` 权限必须为 `0600` 或只读 `0400`。
+- 按数据解析 `.env`；不得 `source`、`eval` 或执行其中内容。
+- `DB_URL` 指向远程数据库主机或地址；部署资产不得把它解释为 Docker 服务名并创建数据库容器。
+- `.env.example` 可保留空数据库凭据，但真实 `.env` 构建时必须完整。
+
+## 3. 本地镜像与构建
+
+基础镜像引用允许使用标签，但必须在构建机本地预先存在。相同标签被人工替换后可能对应不同内容；构建过程不得访问镜像仓库。
+
+`./deploy.sh build` 必须按顺序：
+
+1. 验证根 `.env`、Dockerfile、Compose 和 `.dockerignore`。
+2. 使用 `docker image inspect` 确认两个基础镜像存在。
+3. 使用 `docker build --pull=false` 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest`。
+4. 分别执行 Docker save，生成 `frontend-image.tar`、`backend-image.tar`。
+5. 复制根 `.env`、deploy.sh、docker-compose.yml，生成覆盖全部包内文件的 `manifest.sha256`。
+6. 验证镜像归档各自只含预期标签，验证完整包结构。
+7. 生成 `deploy/<PROJECT_NAME>-docker.tar.gz`，成功后原子替换同名旧包。
+
+构建失败必须保留上一份成功压缩包，并清理本次临时目录。不得维护发布账本、版本号、版本目录、`release.env` 或半成品目录。
+
+## 4. 压缩包契约
+
+压缩包解压根固定为：
+
+```text
+.env
+deploy.sh
+docker-compose.yml
+frontend-image.tar
+backend-image.tar
+manifest.sha256
+```
+
+不得包含源代码、Git、依赖缓存、数据库目录、迁移脚本、秘密副本、符号链接或额外嵌套目录。`.env` 必须保持 owner-only 权限并纳入清单；`.dockerignore` 必须确保 `.env`、秘密、deploy、logs、Git、依赖缓存和虚拟环境不进入镜像构建上下文。
+
+## 5. 服务器一键操作
+
+工程师人工上传并解压单一压缩包。服务器部署根由解压后的 deploy.sh 物理路径确定。
+
+- `./deploy.sh`：校验 `.env` 权限和内容、清单、两个镜像 tar 及预期标签；加载两个镜像；使用一次 `docker compose up -d --force-recreate --no-build --pull never --wait frontend backend` 整体部署并等待健康。
+- `./deploy.sh stop`：同时停止 frontend、backend，保留容器、镜像、交付文件和日志。
+- `./deploy.sh status`：输出当前 Compose 项目的服务状态，不改变 Docker 状态。
+
+不得显示交互菜单，不得接收服务名，不得提供单独运行或替换 frontend/backend 的入口。非法参数必须在 Docker 状态变更前失败。
+
+## 6. Compose、数据库和日志
+
+- Compose 只允许 frontend、backend 两个服务，不设置 `container_name`。
+- 镜像固定为 `${PROJECT_NAME}_frontend:latest`、`${PROJECT_NAME}_backend:latest`，不得提供 fallback。
+- frontend 映射 `${DOCKER_BIND_IP}:${FRONTEND_PORT}:${FRONTEND_PORT}`；backend 同理。
+- 两个服务均使用根 `.env`，并挂载 `./logs:/app/logs`。
+- backend 直接读取 DB_URL、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME、DB_SCHEMA。
+- Compose 不得定义数据库服务、数据库镜像、数据库 volume、数据库端口映射或迁移任务。
+- 前端 Nginx 日志写入 `/app/logs/frontend-access.log`、`/app/logs/frontend-error.log`；后端遵循 wdyy-logging-standard；部署操作写入 `./logs/deploy.log`。
+
+## 7. 失败边界
+
+- 基础镜像缺失、清单错误、镜像标签错误、远程数据库配置不完整或任一服务不健康时明确失败。
+- 禁止 `docker pull`、服务器 `docker build`、镜像 fallback、自动回滚、自动安装和静默跳过。
+- 脚本只操作当前 `PROJECT_NAME` 的 Compose 项目和 frontend、backend 服务，不清理其他项目资源。
+- 旧部署资产由工程师根据实际状态单独迁移；新脚本不得猜测并删除。

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

@@ -9,211 +9,198 @@ const mappings = [
   ['deploy.sh.template', 'deploy.sh', 0o755],
   ['dockerignore.template', '.dockerignore', 0o644],
   ['frontend.Dockerfile.template', 'src/frontend/Dockerfile', 0o644],
-  ['Dockerfile.template', 'src/backend/Dockerfile', 0o644],
-  ['docker-compose.blue-green.yml', 'scripts/deployment/docker-compose.blue-green.yml', 0o644],
+  ['backend.Dockerfile.template', 'src/backend/Dockerfile', 0o644],
+  ['docker-compose.yml', 'scripts/deployment/docker-compose.yml', 0o644],
   ['frontend-container.conf.template', 'scripts/deployment/frontend-container.conf.template', 0o644],
-  ['nginx-upstream.template.conf', 'scripts/deployment/nginx-site.conf', 0o644],
 ];
-
 const sectionNames = ['前端', '后端', '数据库', 'API', '部署'];
-const baseKeys = new Map([
+const fixedSectionKeys = new Map([
   ['前端', ['FRONTEND_URL', 'FRONTEND_PORT']],
   ['后端', ['BACKEND_URL', 'BACKEND_PORT']],
   ['数据库', ['DB_URL', 'DB_PORT', 'DB_USER', 'DB_PASSWORD', 'DB_NAME', 'DB_SCHEMA']],
 ]);
-const deploymentKeys = [
-  'PROJECT_NAME', 'PROJECT_HTTP_PORT', 'DOCKER_BIND_IP',
-  'FRONTEND_BLUE_PORT', 'FRONTEND_GREEN_PORT', 'BACKEND_BLUE_PORT', 'BACKEND_GREEN_PORT',
-  'FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE',
-];
+const exampleDefaults = new Map([
+  ['FRONTEND_URL', '0.0.0.0'], ['FRONTEND_PORT', '5173'],
+  ['BACKEND_URL', '0.0.0.0'], ['BACKEND_PORT', '3000'],
+  ['DB_URL', ''], ['DB_PORT', '5432'], ['DB_USER', ''], ['DB_PASSWORD', ''], ['DB_NAME', ''], ['DB_SCHEMA', ''],
+]);
+const deploymentKeys = ['PROJECT_NAME', 'DOCKER_BIND_IP', 'FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE'];
+const removedKeys = new Set([
+  'PROJECT_HTTP_PORT', 'FRONTEND_BLUE_PORT', 'FRONTEND_GREEN_PORT', 'BACKEND_BLUE_PORT', 'BACKEND_GREEN_PORT',
+  'SERVER_PROJECTS_ROOT', 'NGINX_SOURCE', 'LOG_DIR', 'HOST_LOG_DIR', 'FRONTEND_CONTAINER_PORT',
+  'BACKEND_CONTAINER_PORT', 'BACKEND_LISTEN_HOST', 'DATABASE_MIGRATION_MODE', 'MIGRATIONS_SOURCE',
+  'MIGRATION_RUNNER_SOURCE', 'RELEASE_VERSION',
+]);
 
-function parseEnvironmentStructure(text, relativeTarget, requireExampleDefaults, exampleValues) {
-  const normalized = text.replaceAll('\r\n', '\n');
-  const sections = new Map(sectionNames.map((name) => [name, []]));
-  const encounteredSections = [];
-  const seenKeys = new Set();
-  let currentSection;
+function parseArgs(argv) {
+  let mode;
+  let force = false;
+  let target;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--target') {
+      if (target !== undefined || !argv[index + 1] || argv[index + 1].startsWith('--')) throw new Error('Duplicate or missing --target argument');
+      target = argv[++index];
+    } else if (argument === '--write' || argument === '--check') {
+      if (mode !== undefined) throw new Error('Exactly one of --write or --check is required');
+      mode = argument.slice(2);
+    } else if (argument === '--force') {
+      if (force) throw new Error('Duplicate --force argument');
+      force = true;
+    } else {
+      throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+  if (!mode || target === undefined || (force && mode !== 'write')) {
+    throw new Error('Usage: generate-deployment-files.mjs --target <project-root> (--write [--force] | --check)');
+  }
+  return { mode, force, target: resolve(target) };
+}
 
-  for (const [index, line] of normalized.split('\n').entries()) {
-    if (!line) continue;
-    const heading = line.match(/^# (前端|后端|数据库|API|部署)$/);
+function parseEnvironment(text, relativePath, requireExampleDefaults, deploymentDefaults) {
+  const sections = new Map(sectionNames.map((name) => [name, []]));
+  const headings = [];
+  const seen = new Set();
+  let current;
+  for (const [index, raw] of text.replaceAll('\r\n', '\n').split('\n').entries()) {
+    if (!raw) continue;
+    const heading = raw.match(/^# (前端|后端|数据库|API|部署)$/);
     if (heading) {
-      currentSection = heading[1];
-      encounteredSections.push(currentSection);
+      current = heading[1];
+      headings.push(current);
       continue;
     }
-    if (line.startsWith('#')) continue;
-    if (!currentSection) throw new Error(`${relativeTarget}:${index + 1} must be inside a standard section`);
-    const entry = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
-    if (!entry) throw new Error(`${relativeTarget}:${index + 1} must use KEY=VALUE syntax`);
-    if (seenKeys.has(entry[1])) throw new Error(`${relativeTarget} contains duplicate key: ${entry[1]}`);
-    if (['FRONTEND_CONTAINER_PORT', 'BACKEND_CONTAINER_PORT', 'BACKEND_LISTEN_HOST'].includes(entry[1]) || /_(?:HEALTH|VERSION)_URL$/.test(entry[1])) {
-      throw new Error(`${relativeTarget} contains legacy duplicate configuration: ${entry[1]}`);
-    }
-    seenKeys.add(entry[1]);
-    sections.get(currentSection).push({ key: entry[1], value: entry[2] });
+    if (raw.startsWith('#')) continue;
+    if (!current) throw new Error(`${relativePath}:${index + 1} must be inside a standard section`);
+    const match = raw.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match) throw new Error(`${relativePath}:${index + 1} must use KEY=VALUE syntax`);
+    const [, key, value] = match;
+    if (seen.has(key)) throw new Error(`${relativePath} contains duplicate key: ${key}`);
+    if (removedKeys.has(key) || /_(?:HEALTH|VERSION)_URL$/.test(key)) throw new Error(`${relativePath} contains removed deployment configuration: ${key}`);
+    seen.add(key);
+    sections.get(current).push({ key, value });
   }
-
-  if (encounteredSections.join('|') !== sectionNames.join('|')) {
-    throw new Error(`${relativeTarget} section order must be: ${sectionNames.map((name) => `# ${name}`).join(', ')}`);
+  if (headings.join('|') !== sectionNames.join('|')) {
+    throw new Error(`${relativePath} section order must be: ${sectionNames.map((name) => `# ${name}`).join(', ')}`);
   }
-  for (const [section, expectedKeys] of baseKeys) {
+  for (const [section, expectedKeys] of fixedSectionKeys) {
     const entries = sections.get(section);
-    const actualKeys = entries.map(({ key }) => key);
-    if (actualKeys.join('|') !== expectedKeys.join('|')) {
-      throw new Error(`${relativeTarget} # ${section} keys must be: ${expectedKeys.join(', ')}`);
+    if (entries.map(({ key }) => key).join('|') !== expectedKeys.join('|')) {
+      throw new Error(`${relativePath} # ${section} keys must be: ${expectedKeys.join(', ')}`);
     }
     if (requireExampleDefaults) {
       for (const { key, value } of entries) {
-        if (value !== exampleValues.get(key)) throw new Error(`${relativeTarget} must keep the standard default for ${key}`);
+        if (value !== exampleDefaults.get(key)) throw new Error(`${relativePath} must keep the standard default for ${key}`);
       }
     }
   }
-  const actualDeploymentKeys = sections.get('部署').map(({ key }) => key);
+  const deploymentEntries = sections.get('部署');
+  const actualDeploymentKeys = deploymentEntries.map(({ key }) => key);
   if (actualDeploymentKeys.length !== 0 && actualDeploymentKeys.join('|') !== deploymentKeys.join('|')) {
-    throw new Error(`${relativeTarget} # 部署 keys must be empty or exactly: ${deploymentKeys.join(', ')}`);
-  }
-  if (requireExampleDefaults && sections.get('部署').some(({ key, value }) => !['FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE'].includes(key) && value !== '')) {
-    throw new Error(`${relativeTarget} deployment example values must be empty except base-image defaults`);
+    throw new Error(`${relativePath} # 部署 keys must be empty or exactly: ${deploymentKeys.join(', ')}`);
   }
   if (requireExampleDefaults) {
-    for (const key of ['FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE']) {
-      const entry = sections.get('部署').find((item) => item.key === key);
-      if (entry && entry.value !== exampleValues.get(key)) throw new Error(`${relativeTarget} must keep the standard default for ${key}`);
+    for (const { key, value } of deploymentEntries) {
+      if (value !== deploymentDefaults.get(key)) throw new Error(`${relativePath} must keep the standard deployment default for ${key}`);
     }
   }
   return {
-    extended: actualDeploymentKeys.length === deploymentKeys.length,
-    nonDeploymentKeys: [...seenKeys].filter((key) => !deploymentKeys.includes(key)),
+    extended: deploymentEntries.length === deploymentKeys.length,
+    nonDeploymentKeys: [...seen].filter((key) => !deploymentKeys.includes(key)),
   };
 }
 
-function extendDeploymentSection(text) {
-  return `${text.trimEnd()}\n${deploymentKeys.map((key) => `${key}=${['FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE'].includes(key) ? exampleValues.get(key) : ''}`).join('\n')}\n`;
+function extendDeploymentSection(text, deploymentDefaults) {
+  const additions = deploymentKeys.map((key) => `${key}=${deploymentDefaults.get(key)}`).join('\n');
+  return `${text.trimEnd()}\n${additions}\n`;
 }
 
-const args = process.argv.slice(2);
-let mode;
-let force = false;
-let targetArgument;
-for (let index = 0; index < args.length; index += 1) {
-  const argument = args[index];
-  if (argument === '--target') {
-    if (targetArgument !== undefined || !args[index + 1] || args[index + 1].startsWith('--')) {
-      throw new Error('Duplicate or missing --target argument');
-    }
-    targetArgument = args[index + 1];
-    index += 1;
-  } else if (argument === '--write' || argument === '--check') {
-    if (mode !== undefined) throw new Error('Exactly one of --write or --check is required');
-    mode = argument.slice(2);
-  } else if (argument === '--force') {
-    if (force) throw new Error('Duplicate --force argument');
-    force = true;
-  } else {
-    throw new Error(`Unknown argument: ${argument}`);
+async function readRegularFile(path, label, allowMissing = false) {
+  try {
+    const info = await lstat(path);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error(`${label} must be a regular file`);
+    return await readFile(path);
+  } catch (error) {
+    if (allowMissing && error.code === 'ENOENT') return undefined;
+    throw error;
   }
 }
-if (!mode || targetArgument === undefined || (force && mode !== 'write')) {
-  throw new Error('Usage: generate-deployment-files.mjs --target <project-root> (--write [--force] | --check)');
+
+async function atomicWrite(path, content, mode) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.wdyy-${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, content, { flag: 'wx', mode });
+    await chmod(temporary, mode);
+    await rename(temporary, path);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
 }
 
-const targetRoot = resolve(targetArgument);
-const targetStat = await stat(targetRoot);
-if (!targetStat.isDirectory()) throw new Error(`Target project root is not a directory: ${targetRoot}`);
+const { mode, force, target } = parseArgs(process.argv.slice(2));
+const targetInfo = await stat(target);
+if (!targetInfo.isDirectory()) throw new Error(`Target project root is not a directory: ${target}`);
+
+const deploymentTemplate = await readFile(join(templatesRoot, 'env.example.template'), 'utf8');
+const deploymentDefaults = new Map([...deploymentTemplate.matchAll(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/gm)].map((match) => [match[1], match[2]]));
+if (deploymentKeys.some((key) => !deploymentDefaults.has(key))) throw new Error('Deployment environment template is incomplete');
 
-const environmentTemplate = await readFile(join(templatesRoot, 'env.example.template'), 'utf8');
-const exampleValues = new Map(
-  [...environmentTemplate.matchAll(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/gm)].map((match) => [match[1], match[2]]),
-);
 const environmentPlans = [];
-for (const [relativeTarget, expectedMode, requireExampleDefaults] of [['.env', 0o600, false], ['.env.example', 0o644, true]]) {
-  const target = join(targetRoot, relativeTarget);
-  const targetInfo = await lstat(target);
-  if (targetInfo.isSymbolicLink() || !targetInfo.isFile()) throw new Error(`Environment target must be a regular file: ${relativeTarget}`);
-  const existing = await readFile(target, 'utf8');
-  const structure = parseEnvironmentStructure(existing, relativeTarget, requireExampleDefaults, exampleValues);
+for (const [relativePath, expectedMode, requireDefaults] of [['.env', 0o600, false], ['.env.example', 0o644, true]]) {
+  const path = join(target, relativePath);
+  const existingBuffer = await readRegularFile(path, relativePath);
+  const existing = existingBuffer.toString('utf8');
+  const parsed = parseEnvironment(existing, relativePath, requireDefaults, deploymentDefaults);
   environmentPlans.push({
-    target,
-    relativeTarget,
-    expectedMode,
-    existing,
-    nonDeploymentKeys: structure.nonDeploymentKeys,
-    expected: structure.extended ? existing : extendDeploymentSection(existing),
+    path, relativePath, expectedMode,
+    existing: existingBuffer,
+    expected: Buffer.from(parsed.extended ? existing : extendDeploymentSection(existing, deploymentDefaults)),
+    nonDeploymentKeys: parsed.nonDeploymentKeys,
   });
 }
 if (environmentPlans[0].nonDeploymentKeys.join('|') !== environmentPlans[1].nonDeploymentKeys.join('|')) {
   throw new Error('.env and .env.example variable names must remain consistent');
 }
 
-const differences = [];
-for (const [templateName, relativeTarget, expectedMode] of mappings) {
-  const source = join(templatesRoot, templateName);
-  const target = join(targetRoot, relativeTarget);
-  const expected = await readFile(source);
-  let existing;
-  try {
-    const targetInfo = await lstat(target);
-    if (targetInfo.isSymbolicLink() || !targetInfo.isFile()) throw new Error(`Generated target must be a regular file: ${relativeTarget}`);
-    existing = await readFile(target);
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
+const generatedPlans = [];
+for (const [templateName, relativePath, expectedMode] of mappings) {
+  const expected = await readFile(join(templatesRoot, templateName));
+  const path = join(target, relativePath);
+  const existing = await readRegularFile(path, relativePath, true);
+  generatedPlans.push({ path, relativePath, expectedMode, expected, existing });
+}
 
-  const differs = !existing || !existing.equals(expected);
-  if (mode === 'check') {
-    if (differs) differences.push(relativeTarget);
-    if (!differs && relativeTarget === 'deploy.sh') {
-      const info = await stat(target);
-      if ((info.mode & 0o111) === 0) differences.push(`${relativeTarget} (not executable)`);
-    }
-    continue;
-  }
-  if (differs && existing && !force) {
-    differences.push(relativeTarget);
-    continue;
-  }
-  if (differs) {
-    await mkdir(dirname(target), { recursive: true });
-    const temporary = `${target}.wdyy-${process.pid}.tmp`;
-    try {
-      await writeFile(temporary, expected, { flag: 'wx', mode: expectedMode });
-      await chmod(temporary, expectedMode);
-      await rename(temporary, target);
-    } catch (error) {
-      await unlink(temporary).catch(() => {});
-      throw error;
-    }
-  } else {
-    await chmod(target, expectedMode);
-  }
+const differingGenerated = generatedPlans.filter(({ existing, expected }) => existing && !existing.equals(expected)).map(({ relativePath }) => relativePath);
+if (mode === 'write' && differingGenerated.length && !force) {
+  throw new Error(`Refusing to overwrite differing deployment files without --force: ${differingGenerated.join(', ')}`);
 }
 
-if (mode === 'write' && differences.length) {
-  throw new Error(`Refusing to overwrite differing deployment files without --force: ${differences.join(', ')}`);
+const differences = [];
+for (const plan of generatedPlans) {
+  const differs = !plan.existing || !plan.existing.equals(plan.expected);
+  if (mode === 'check') {
+    if (differs) differences.push(plan.relativePath);
+    else {
+      const info = await stat(plan.path);
+      if ((info.mode & 0o777) !== plan.expectedMode) differences.push(`${plan.relativePath} (mode)`);
+    }
+  } else if (differs) await atomicWrite(plan.path, plan.expected, plan.expectedMode);
+  else await chmod(plan.path, plan.expectedMode);
 }
 
 for (const plan of environmentPlans) {
-  if (plan.existing !== plan.expected) {
-    if (mode === 'check') differences.push(plan.relativeTarget);
+  const differs = !plan.existing.equals(plan.expected);
+  if (mode === 'check') {
+    if (differs) differences.push(plan.relativePath);
     else {
-      const temporary = `${plan.target}.wdyy-${process.pid}.tmp`;
-      try {
-        await writeFile(temporary, plan.expected, { flag: 'wx', mode: plan.expectedMode });
-        await chmod(temporary, plan.expectedMode);
-        await rename(temporary, plan.target);
-      } catch (error) {
-        await unlink(temporary).catch(() => {});
-        throw error;
-      }
+      const info = await stat(plan.path);
+      if ((info.mode & 0o777) !== plan.expectedMode) differences.push(`${plan.relativePath} (mode)`);
     }
-  } else if (mode === 'write') {
-    await chmod(plan.target, plan.expectedMode);
-  }
+  } else if (differs) await atomicWrite(plan.path, plan.expected, plan.expectedMode);
+  else await chmod(plan.path, plan.expectedMode);
 }
 
-if (differences.length) {
-  const action = mode === 'check' ? 'Generated deployment files differ' : 'Refusing to overwrite differing deployment files without --force';
-  throw new Error(`${action}: ${differences.join(', ')}`);
-}
-process.stdout.write(`${mode === 'write' ? 'generated' : 'verified'} deterministic deployment files in ${targetRoot}\n`);
+if (differences.length) throw new Error(`Generated deployment files differ: ${differences.join(', ')}`);
+process.stdout.write(`${mode === 'write' ? 'generated' : 'verified'} unified Docker delivery files in ${target}\n`);