@wdyy/skills 0.1.6 → 0.1.8

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

@@ -7,8 +7,8 @@
     },
     {
       "name": "wdyy-deployment-standard",
-      "description": "为无 CI/CD 的 Linux 生产环境生成 pnpm 开发流程、本地 deploy.sh build 一键打包、AGENTS.md 自动发布编号、deploy 目录人工上传及 deploy.sh start 蓝绿部署与回滚规范。Use when 规划、实现、审查或执行手工生产部署时。",
-      "files": ["SKILL.md", "agents/openai.yaml", "reference/linux-deployment-rules.md", "scripts/validate-deployment-package.mjs", "scripts/validate-deployment-package.test.mjs", "templates/Dockerfile.template", "templates/deploy.sh.template", "templates/docker-compose.blue-green.yml", "templates/dockerignore.template", "templates/nginx-upstream.template.conf"]
+      "description": "基于标准五段根 .env，为无 CI/CD 的多项目 Linux 服务器生成确定性的前后端双 Docker 发布配置、本地 deploy.sh build 完整打包、人工上传及按独立端口执行蓝绿启动、替换、重启、停止、删除和回滚。Use when 规划、实现、审查或执行 `/xxzx/home/项目目录` 下的手工生产部署时。",
+      "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"]
     },
     {
       "name": "wdyy-api-standard",

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

@@ -1,81 +1,73 @@
 ---
 name: wdyy-deployment-standard
-description: 为无 CI/CD 的 Linux 生产环境生成 pnpm 开发流程、本地 deploy.sh build 一键打包、AGENTS.md 自动发布编号、deploy 目录人工上传及 deploy.sh start 蓝绿部署与回滚规范。Use when 规划、实现、审查或执行手工生产部署时。
+description: 基于标准五段根 .env，为无 CI/CD 的多项目 Linux 服务器生成确定性的前后端双 Docker 发布配置、本地 deploy.sh build 完整打包、人工上传及按独立端口执行蓝绿启动、替换、重启、停止、删除和回滚。Use when 规划、实现、审查或执行 `/xxzx/home/项目目录` 下的手工生产部署时。
 ---
 
 # 企业部署规范
 
 ## Overview
 
-将项目开发与生产发布分离为 `pnpm dev`、本地一键打包、人工全目录上传和服务器一键启动，同时保留版本化前端、后端蓝绿切流、健康检查和回滚。
+把开发、构建、上传和服务器操作分开：开发只用 `pnpm dev`；本地用 `./deploy.sh build` 生成前后端双镜像和完整 `deploy/`；工程师人工上传；服务器按根 `.env` 的项目端口执行成对蓝绿切流。
 
-## 协作边界
+## 使用边界
 
-生成目标项目根目录 `deploy.sh` 及其实际依赖的部署配置。工程师负责人工上传 `deploy/` 下全部文件并在服务器手动执行脚本；不得在脚本中上传、拉取代码、安装依赖或替代 GO/NO-GO 决策。
+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` 和全部行为测试。
 
-## 输入与输出
+## 固定契约
 
-- 输入：目标项目真实的 pnpm scripts、前后端构建路径、Dockerfile、版本接口、健康检查、数据库迁移、Nginx 权限及服务器 `.env.production`。
-- 输出：项目根目录 `deploy.sh`、`.dockerignore`、后端 Dockerfile、蓝绿 Compose、版本化前端 Nginx 配置，以及 `./deploy/<YYYYMMDD-NNN>/` 完整发布包。
-- 读取 [Linux 部署规则](reference/linux-deployment-rules.md)，按目标项目实际结构使用 `templates/`，并运行 `scripts/validate-deployment-package.mjs`。
+- 项目名只允许小写字母、数字和下划线，并与服务器目录 `/xxzx/home/<项目名称>` 对应。
+- 两个镜像必须精确命名为 `<项目名称>_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` 排除，且不得进入版本目录或任一镜像。
+- 环境文件固定按“前端、后端、数据库、API、部署”排列；部署生成器保留前四段和已有值，只扩充部署段。
+- `DATABASE_MIGRATION_MODE=manual` 时只打包迁移与执行脚本；`none` 时不要求数据库文件。任何部署命令都不得自动访问数据库。
+- 相同输入生成的 deploy.sh、Compose、Nginx 配置必须字节一致；版本指针、镜像归档和 manifest 可随发布变化。
 
-## 执行步骤
+## 工作流
 
-1. 开发测试阶段只使用项目根目录 `pnpm dev`，不得由部署脚本管理开发服务或数据库。
-2. 生成无版本参数的 `./deploy.sh build`。从目标项目 `AGENTS.md` 的固定发布记录表读取当天最大序号，自动生成 `YYYYMMDD-NNN`。
-3. 在本地依次通过测试、lint、类型检查、`pnpm build`、前端版本路径、镜像和发布包校验；任一步失败不得写发布记录或暴露半成品。
-4. 重新生成只含本次版本的 `deploy/`：根部放置 `deploy.sh`、`release.env`，版本目录包含前端包、后端镜像、完整迁移、迁移执行器、Compose、Nginx 配置和校验清单。
-5. 全部校验成功后，向 `AGENTS.md` 的“发布记录”表写入版本号与构建时间。
-6. 工程师将 `deploy/` 下全部内容人工上传到服务器指定目录；该目录即部署根目录。
-7. 在服务器执行无版本参数的 `./deploy.sh start`。脚本从 `release.env` 读取版本，并在任何变更前校验文件、校验清单和服务器 `.env.production`。
-8. 使用原生 `psql` 执行向前兼容迁移，在非活动颜色启动后端；健康检查和版本接口通过后切换 Nginx upstream，再原子切换前端 `current`。
-9. 保留旧颜色和前端 release 作为上一版本；提供 `stop`、`restart`、`status` 和 `rollback <version>`。
-10. blue 与 green 共同将服务器部署根目录 `./logs` 挂载到 `/app/logs`，不得设置 `LOG_DIR`、`HOST_LOG_DIR` 或创建实例日志子目录。
+1. 使用 `pnpm dev` 完成开发测试。
+2. 执行不带额外参数的 `./deploy.sh build`；从 `AGENTS.md` 唯一“发布记录”表生成 `YYYYMMDD-NNN`。
+3. 依次通过测试、lint、类型检查、构建、双镜像语义检查、包校验和配置确定性检查；成功后才替换 `deploy/` 并写发布记录。
+4. 人工把 `deploy/` 全部内容上传到 `.env` 声明的 `<SERVER_PROJECTS_ROOT>/<PROJECT_NAME>`；生产值不得通过命令行传入。
+5. 数据库模式为 manual 时，由工程师单独执行版本包中的迁移脚本并确认结果。
+6. 首次部署执行 `./deploy.sh start`；后续新版本执行 `./deploy.sh replace`。
+7. 通过 `restart`、`stop`、`status`、`rollback <version>` 管理当前项目；`remove` 只删除本项目容器、网络及两个精确镜像仓库。
+
+## Nginx 多项目隔离
+
+- 运维只在服务器初次接入时让共享 Nginx include `/xxzx/home/*/nginx/site.conf`；部署脚本不得编辑该全局配置。
+- 每个项目只写自身 `nginx/site.conf` 和 `nginx/active-upstreams.conf`。
+- upstream 名称由严格项目名确定，不接受自由文本配置。
+- 在共享文件锁内检查其他项目配置和运行中容器的实际发布端口、安装候选配置、运行进程级 `nginx -t` 和 reload；失败时恢复本项目旧文件。
+- 其他项目配置错误可以阻止本次 reload，但不得强制跳过检查或改写其他项目文件。
 
 ## 禁止事项
 
-- 不得接受人工输入 build 版本号或 `start <version>` 旧语法。
-- 不得以扫描 `deploy/` 目录代替 `AGENTS.md` 发布账本。
-- 不得把 `.env`、`.env.production`、凭据或其他生产秘密打入 `deploy/`。
-- 不得在缺少已验证 `.dockerignore` 的情况下用项目根目录构建后端镜像。
-- 不得在脚本、Compose、Dockerfile 或 Nginx 中硬编码 URL、端口或 IP；全部由 `.env` 或服务器 `.env.production` 明确提供。
-- 不得直接覆盖正在服务的前端 `dist`。
-- 不得先停止旧后端容器再启动新容器。
-- 不得以 PM2 或 systemd 作为后端主部署方案。
-- 不得在无健康检查、版本标识或可演练回滚的情况下发布。
-- 不得在 `deploy.sh` 中执行 SCP、拉取代码、访问制品仓库或静默安装依赖。
-- 不得把“保留旧 release 目录”等同于旧资源可访问；资源 URL 必须包含版本。
-- 不得将日志挂载到项目根目录 `./logs` 之外，或为 blue、green 配置不同日志目录。
-
-## Red Flags
-
-- `build` 成功前修改 `AGENTS.md`，或失败后仍留下新的可上传目录。
-- 发布包依赖目标项目工作树中未上传的迁移执行器、配置或脚本。
-- `start` 依赖固定 `/srv/<project>`、调用者当前目录或人工版本参数。
-- 发布脚本在新版本通过健康检查前修改 upstream。
-- 前端目录被直接覆盖，或发布计划包含破坏性迁移。
-- Compose 包含 `LOG_DIR`、`HOST_LOG_DIR`、实例日志子目录或非 `../../logs:/app/logs` 的日志挂载。
+- 不得接受人工 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 配置。
+- 不得以字符串关键字存在代替命令行为、失败恢复和资源边界测试。
 
 ## Verification
 
-- [ ] 新容器通过健康检查并返回目标版本。
-- [ ] upstream 切换后新请求命中新版本，旧资源在保留窗口不返回 404。
-- [ ] 回滚脚本在演练环境恢复旧版本。
-- [ ] 数据库变更的兼容性已审查。
-- [ ] `build` 无版本参数，发布编号来自格式正确且唯一的 `AGENTS.md` 发布记录。
-- [ ] `deploy/` 只含本次完整发布包且不含生产秘密。
-- [ ] `start` 无版本参数，通过脚本物理位置识别服务器部署根目录。
-- [ ] `deploy.sh` 不包含上传、拉取代码或安装依赖行为。
-- [ ] blue 与 green 都将项目根目录 `./logs` 挂载到 `/app/logs`，且不存在其他日志目录。
-
-任一步骤失败时保持或恢复旧 upstream，保留失败容器日志并报告失败环节；不得强制切流或删除旧版本掩盖问题。
-
-## Common Rationalizations
-
-| 合理化说法 | 事实 |
-|---|---|
-| “版本号手工输入更快” | 手工参数可能与上传包不一致，版本必须来自发布账本和 `release.env`。 |
-| “迁移脚本服务器上已经有” | 发布包必须自包含，不能依赖未上传的项目工作树。 |
-| “停几秒没关系” | 发布规范要求后端无先停后启的中断窗口。 |
-| “覆盖 dist 最简单” | 旧页面会引用旧 hash 文件，覆盖会造成资源 404。 |
-| “小字段改动无需兼容” | 滚动与回滚期间新旧版本会并存。 |
+- [ ] 两个镜像名称、标签和版本 label 精确匹配发布版本。
+- [ ] 四个服务均使用根 `.env`，且只挂载 `../../logs:/app/logs`。
+- [ ] `.env` 与 `.env.example` 的五段、变量顺序一致，部署段键相同且无重复 URL/端口配置。
+- [ ] 外部项目端口唯一；Nginx 一次同时切换前后端，失败恢复旧流量和状态。
+- [ ] start、replace、restart、stop、remove、status、rollback 行为与资源范围均通过测试。
+- [ ] manual/none 两种数据库模式均通过测试，部署脚本不存在数据库执行路径。
+- [ ] 连续两次构建的配置文件一致，失败不写发布记录、不暴露半成品。
+- [ ] `deploy/` 含根 `.env`，但版本目录、Docker 上下文和镜像不含秘密文件。
+- [ ] 替换或删除容器后，项目根 `logs/` 内容仍保留。
+
+任一步失败必须明确报告具体阶段并保持或恢复本项目原流量；不得以兜底、静默跳过、强制切流或删除失败证据规避问题。

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Enterprise Deployment Standard"
-  short_description: "Build and start complete manual deployment packages"
-  default_prompt: "Use $wdyy-deployment-standard to build a versioned deploy directory and prepare its manual server start."
+  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."

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

@@ -1,131 +1,135 @@
 # Linux 部署规则
 
-## 目标项目文件
+## 目录和受控源文件
 
-按目标项目真实结构生成并维护以下受版本控制文件：
+目标项目必须维护：
 
 ```text
 deploy.sh
 .dockerignore
+src/frontend/Dockerfile
 src/backend/Dockerfile
-scripts/apply-migrations.sh
 scripts/deployment/docker-compose.blue-green.yml
+scripts/deployment/frontend-container.conf.template
 scripts/deployment/nginx-site.conf
+.env.example
 ```
 
-- `deploy.sh` 同时提供本地 `build` 和服务器 `start`、`stop`、`restart`、`status`、`rollback`。
-- Dockerfile 必须接收同一发布版本，使镜像标签和后端版本接口返回 `YYYYMMDD-NNN`。
-- `.dockerignore` 必须排除 `.env`、`.env.*`、密钥、凭据、`deploy/`、`logs/`、`.git/`、`node_modules/`、`venv/` 和 `.pnpm-store/`；仅允许明确反向包含 `.env.example`。
-- Compose 与 Nginx 源文件不得位于生成目录 `deploy/`，否则下一次 build 会删除部署源配置。
-- `scripts/apply-migrations.sh` 必须来自数据库 Skill 的已确认迁移契约，且随每次发布复制到版本目录。
-- 根据目标项目的 pnpm workspace 和构建输出调整模板变量；不得保留不存在的示例路径。
-- 在项目 `.env` 提供 `PROJECT_NAME` 与 `BACKEND_CONTAINER_PORT` 供本地 build 使用；不得在脚本或 Dockerfile 中写默认端口。
+这些文件必须由 `scripts/generate-deployment-files.mjs --target <project-root> --write` 按固定映射原子生成，templates 是唯一源。既有差异默认失败，不得静默覆盖；工程师审查并确认后才允许 `--force`。生成后执行 `--check`。build 必须原样复制 deploy.sh、Compose 和 Nginx 模板，不得根据运行顺序产生随机内容；相同输入连续构建时这些配置的 SHA-256 必须一致。
+
+## 根 .env
+
+根 `.env` 是本地 build、上传包和服务器 Compose 的唯一配置文件。`.env` 与 `.env.example` 固定按“前端、后端、数据库、API、部署”排列；部署生成器保留前四段与已有值，只向两个文件的部署段追加同名空键。`.env.example` 必须直接采用 `templates/env.example.template` 的键、顺序与非敏感默认值。脚本必须按数据解析，不得 `source` 或 `eval`。部署前根 `.env` 至少要求：
+
+```dotenv
+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=
+PROJECT_NAME=example_project
+SERVER_PROJECTS_ROOT=/xxzx/home
+PROJECT_HTTP_PORT=9099
+DOCKER_BIND_IP=127.0.0.1
+FRONTEND_BLUE_PORT=19091
+FRONTEND_GREEN_PORT=19092
+BACKEND_BLUE_PORT=19093
+BACKEND_GREEN_PORT=19094
+FRONTEND_BASE_IMAGE=nginx:1.29-alpine@sha256:<confirmed-digest>
+BACKEND_BASE_IMAGE=node:24-bookworm-slim@sha256:<confirmed-digest>
+DATABASE_MIGRATION_MODE=none
+```
+
+`FRONTEND_URL`、`FRONTEND_PORT`、`BACKEND_URL`、`BACKEND_PORT` 是应用监听的唯一来源；容器、蓝绿和项目入口的健康/版本 URL 必须由对应主机、端口与固定路径确定性构造。不得增加 `FRONTEND_CONTAINER_PORT`、`BACKEND_CONTAINER_PORT`、`BACKEND_LISTEN_HOST`、`*_HEALTH_URL` 或 `*_VERSION_URL`。通配监听地址 `0.0.0.0` 仅在主动本机探测时转换为 `127.0.0.1`。
+
+部署示例值只说明字段，生成目标项目后必须由工程师确认 `.env` 实际值，不得保留占位符或示例部署端口。`PROJECT_NAME` 只允许 `^[a-z][a-z0-9_]*$`。所有宿主机端口必须互不相同且在 1–65535；基础镜像必须使用 digest 固定。数据库连接键允许为空，但项目使用数据库时必须填写真实值。
+
+`.env` 权限必须为 `0600` 或只读的 `0400`。部署脚本只把明确的部署键载入自身环境；数据库密码、JWT 等其他应用键保留在文件中供 Compose 注入容器，不得改变脚本的 `PATH`、Shell 选项或命令行为。
+
+可选路径键为 `FRONTEND_DOCKERFILE`、`BACKEND_DOCKERFILE`、`MIGRATIONS_SOURCE`、`MIGRATION_RUNNER_SOURCE`、`DEPLOY_CONFIG_DIR`；未设置时只能使用与目标项目真实结构一致且已验证的标准路径。
 
-## 开发与本地打包
+## Docker 与日志
 
-1. 开发测试阶段执行 `pnpm dev`，不得由部署脚本启动或管理数据库。
-2. 开发测试完成后，只执行无额外参数的 `./deploy.sh build`。
-3. build 依次执行目标项目已确认的测试、lint、类型检查、`pnpm build`、版本化前端校验、Docker 镜像构建与检查、完整发布包校验。
-4. 前端构建使用 `/releases/<version>/` 资源基路径，后端镜像标签和版本接口使用同一个 `<version>`。
-5. 任一步失败必须返回非零状态并报告具体环节，不得跳过、降级或形成可上传结论。
+- 前端镜像：`${PROJECT_NAME}_frontend:${RELEASE_VERSION}`。
+- 后端镜像：`${PROJECT_NAME}_backend:${RELEASE_VERSION}`。
+- 四个服务由同一个 `docker compose --project-name "$PROJECT_NAME"` 管理，不设置 `container_name`。
+- 四个服务都使用 `../../.env`，复用 `FRONTEND_PORT`、`BACKEND_PORT`、`FRONTEND_URL`、`BACKEND_URL`，并且只有 `../../logs:/app/logs` 一个日志挂载。
+- 前端 Nginx 容器的 access/error 文件直接写入 `/app/logs/frontend-<color>-*.log`；不得创建子目录。
+- 后端必须把自身日志直接写入 `/app/logs`，不得依赖容器可写层保存持久日志。
+- `.dockerignore` 必须排除 `.env`、`.env.*`、密钥、凭据、deploy、logs、Git、依赖缓存和虚拟环境。
 
-## AGENTS.md 发布账本
+## 发布账本与本地包
 
-`AGENTS.md` 是发布序号的唯一来源。发布记录使用且只使用以下两列：
+`AGENTS.md` 只允许一个固定两列表：
 
 ```markdown
 ## 发布记录
 
 | 版本号 | 构建时间 |
 |---|---|
-| 20260730-001 | 2026-07-30 09:30:00 +08:00 |
+| 20260808-001 | 2026-08-08 09:30:00 +08:00 |
 ```
 
-build 必须：
-
-1. 要求项目根目录存在可读写的 `AGENTS.md`。
-2. 要求最多存在一个标题完全等于 `## 发布记录` 的章节。
-3. 严格验证表头、分隔行以及所有 `YYYYMMDD-NNN` 和构建时间记录；版本不得重复，序号必须为 `001` 至 `999`。
-4. 读取本地当前日期，取当天最大序号加一；当天无记录时使用 `001`。
-5. 在全部发布门禁和包校验成功后才原子写入版本号与构建时间。
-6. 章节不存在时，在首次成功 build 后追加固定章节和表格。
-7. 账本损坏、章节重复、版本重复或当天已到 `999` 时明确失败。
-
-不得接受人工 build 版本参数，不得扫描 `deploy/` 推导序号。构建人员必须先同步版本控制中的发布记录；本规范不提供跨未同步工作区的中央编号服务。
-
-## 本地 deploy 目录
-
-每次 build 先在项目根目录外显路径之外生成临时包，全部校验通过后重新生成只含本次版本的 `deploy/`：
+build 使用项目级原子锁，严格验证账本后生成当天下一序号。全部门禁、双镜像、包结构和确定性校验通过后才写账本。失败必须保留原 deploy 和原账本。
 
 ```text
 deploy/
+├── .env
 ├── deploy.sh
 ├── release.env
 └── YYYYMMDD-NNN/
-    ├── frontend.tar.gz
+    ├── frontend-image.tar
     ├── backend-image.tar
     ├── manifest.sha256
-    ├── database/migrations/
-    ├── scripts/apply-migrations.sh
     ├── docker/docker-compose.blue-green.yml
-    └── nginx/site.conf
+    ├── nginx/site.conf
+    └── database/                 # 仅 manual 模式
+        ├── migrations/
+        └── apply-migrations.sh
 ```
 
-- `release.env` 只允许声明 `RELEASE_VERSION=YYYYMMDD-NNN`。
-- `manifest.sha256` 覆盖版本目录中除清单本身外的全部文件。
-- `deploy/` 只包含本次版本，不承担历史账本职责。
-- `.env`、`.env.production`、访问令牌、私钥、证书、密码和其他生产秘密不得进入 `deploy/`。
-- build 必须在 Docker 构建前验证项目根目录 `.dockerignore` 的固定秘密与生成目录排除项，防止秘密进入 `backend-image.tar`。
-- 任一步失败必须清理本次临时输出，不得修改发布记录或留下半成品。
+`release.env` 只包含当前版本。manifest 覆盖版本目录内除自身外的全部普通文件，禁止符号链接、硬链接秘密、绝对路径和 `..`。根 `.env` 可上传，但版本目录与镜像不得包含它。
 
-## 人工上传
+## 服务器部署和 Nginx
 
-工程师将本地 `deploy/` 下全部内容人工上传到服务器指定目录。该目录本身就是部署根目录，例如本地 `deploy/deploy.sh` 上传后对应 `<deploy-root>/deploy.sh`，不得在服务器额外嵌套一层固定 `deploy/`。
+上传目标必须是 `${SERVER_PROJECTS_ROOT}/${PROJECT_NAME}`，生产值为 `/xxzx/home/<项目名称>`。脚本通过自身物理路径验证该关系，不依赖调用者当前目录。
 
-`deploy.sh` 不得执行 SCP、rsync、Git 拉取、制品仓库下载或依赖安装。生产 `.env.production` 由服务器单独保管，不随上传包传输。
+共享 Nginx 主配置由运维预先 include `/xxzx/home/*/nginx/site.conf`。项目脚本不得写 `/etc/nginx` 或其他项目，只维护：
 
-服务器 `.env.production` 必须明确提供 `PROJECT_NAME`、`DATABASE_URL`、`BACKEND_BIND_IP`、`BACKEND_LISTEN_HOST`、`BACKEND_CONTAINER_PORT`、`BACKEND_CONTAINER_HEALTH_URL`、`BLUE_PORT`、`GREEN_PORT`、`BLUE_HEALTH_URL`、`GREEN_HEALTH_URL`、`BLUE_VERSION_URL`、`GREEN_VERSION_URL`、`BLUE_UPSTREAM`、`GREEN_UPSTREAM` 和 `BACKEND_PROXY_URL`。`BACKEND_PROXY_URL` 必须是仅包含合法 Nginx upstream 名称的 `http://<name>` 或 `https://<name>`。URL、端口和 IP 不得在脚本、Compose、Dockerfile 或 Nginx 模板中设置默认值。
+```text
+<project-root>/nginx/site.conf
+<project-root>/nginx/active-upstreams.conf
+```
 
-## 服务器目录与 start
+site 监听 `PROJECT_HTTP_PORT`，并带项目名、外部端口及四个 Docker 宿主机端口标记。首次部署和端口变更必须在共享锁内检查展开的 Nginx 配置、其他标准项目 site 以及运行中容器的实际发布端口；任一外部端口或 blue/green 宿主机端口重复、其他项目缺少端口标记或不能证明唯一时失败。候选 site 与前后端 upstream 一起安装，`nginx -t` 或 reload 失败时恢复旧文件。
 
-上传后服务器目录形态为：
+## 命令
 
-```text
-<deploy-root>/
-├── deploy.sh
-├── release.env
-├── YYYYMMDD-NNN/
-├── .env.production
-├── logs/
-├── releases/
-├── state/
-├── current -> releases/<active-version>
-└── nginx/
-    ├── site.conf
-    └── backend-active.conf
-```
+- `./deploy.sh start`：只允许无活动状态的首次 blue 部署。
+- `./deploy.sh replace`：只允许已有活动状态且 release.env 指向不同新版本。
+- `./deploy.sh restart`：重新创建并验证当前颜色的两个容器，不改变流量颜色和版本。
+- `./deploy.sh stop`：停止当前颜色的两个容器，保留所有文件和状态。
+- `./deploy.sh remove`：删除 Compose project 下四个容器及网络，并删除两个精确项目镜像仓库的全部标签；保留日志、包、状态和 Nginx 文件。
+- `./deploy.sh status`：报告 active/previous 和四服务状态。
+- `./deploy.sh rollback <version>`：只允许 previous 中已保留且健康的成对容器。
+
+除 rollback 的版本外，命令不得接受额外参数。
+
+## 数据库
+
+- `DATABASE_MIGRATION_MODE=none`：版本包不要求数据库目录。
+- `DATABASE_MIGRATION_MODE=manual`：必须打包完整迁移目录和可执行脚本。
+- deploy.sh 的任何服务器命令都不得调用迁移脚本、psql 或数据库客户端。
+- build 完成和服务器 start/replace 必须明确提示 manual 操作尚需工程师单独执行，不得声称已迁移。
+
+## 失败边界
 
-1. 在部署根目录执行无额外参数的 `./deploy.sh start`。
-2. 脚本通过自身绝对路径确定部署根目录，不依赖调用者当前目录，不使用固定 `/srv/<project>`。
-3. start 严格读取 `release.env`，校验版本格式、版本目录、必需文件和全部 SHA-256；传入版本参数必须失败。
-4. `.env.production` 缺失或不可读时，在加载镜像、迁移和切流前失败。
-5. 安全解压前端到不可变 `releases/<version>`；确认 `index.html` 与版本化资源路径后才允许切换 `current`。
-6. 加载精确标签的后端镜像，使用版本包内的迁移执行器执行尚未执行的向前兼容迁移。
-7. 在非活动颜色启动新容器；健康检查和版本接口返回目标版本后才切换 Nginx upstream，再原子切换前端 `current`。
-8. 保留旧颜色和旧前端 release 到观测窗口结束，默认保留最近五个版本。
-9. `rollback <version>` 只允许切回已保留、健康且数据库兼容的上一版本。
-
-## 路径与日志
-
-- 版本 Compose 位于 `<deploy-root>/<version>/docker`。
-- blue 与 green 共同使用 `../../logs:/app/logs`，使宿主机部署根目录 `./logs` 对应容器 `/app/logs`。
-- 不得设置 `LOG_DIR`、`HOST_LOG_DIR`，不得创建服务、实例、日期、颜色或其他日志子目录。
-- Nginx 包内模板使用明确占位符；start 按脚本物理路径渲染到 `<deploy-root>/nginx/site.conf`。
-- Nginx 主配置必须由工程师预先包含或链接该 site 文件，并授予脚本执行 `nginx -t` 与 reload 的权限。
-
-## 失败与回滚
-
-- 包校验、生产配置、解压、镜像、迁移、容器启动、健康检查、版本检查、Nginx 校验或 reload 任一步失败时，保持当前 upstream 和前端 `current`。
-- Nginx 切换失败时恢复原 upstream 内容，再验证并 reload；必须明确报告失败。
-- 不得强制切流、先停止旧容器、删除旧版本、静默安装工具或吞掉错误。
-- `stop`、`restart`、`status` 和 `rollback` 必须从持久 active/previous 状态解析对应版本目录，不得依赖上传者重复输入当前版本。
+- 新颜色前后端全部健康且后端版本正确前，不得修改 Nginx 或活动状态。
+- Nginx candidate、全局校验、reload 或状态提交失败时，必须恢复本项目旧配置和旧状态。
+- 不得停止旧颜色掩盖新颜色失败；不得修改、停止或删除其他项目任何资源。
+- `remove` 不得删除 logs、上传版本目录、release.env、状态文件或 Nginx 配置。

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

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { chmod, lstat, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const templatesRoot = join(skillRoot, 'templates');
+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],
+  ['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([
+  ['前端', ['FRONTEND_URL', 'FRONTEND_PORT']],
+  ['后端', ['BACKEND_URL', 'BACKEND_PORT']],
+  ['数据库', ['DB_URL', 'DB_PORT', 'DB_USER', 'DB_PASSWORD', 'DB_NAME', 'DB_SCHEMA']],
+]);
+const deploymentKeys = [
+  'PROJECT_NAME', 'SERVER_PROJECTS_ROOT', 'PROJECT_HTTP_PORT', 'DOCKER_BIND_IP',
+  'FRONTEND_BLUE_PORT', 'FRONTEND_GREEN_PORT', 'BACKEND_BLUE_PORT', 'BACKEND_GREEN_PORT',
+  'FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE', 'DATABASE_MIGRATION_MODE',
+];
+
+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;
+
+  for (const [index, line] of normalized.split('\n').entries()) {
+    if (!line) continue;
+    const heading = line.match(/^# (前端|后端|数据库|API|部署)$/);
+    if (heading) {
+      currentSection = heading[1];
+      encounteredSections.push(currentSection);
+      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 (encounteredSections.join('|') !== sectionNames.join('|')) {
+    throw new Error(`${relativeTarget} section order must be: ${sectionNames.map((name) => `# ${name}`).join(', ')}`);
+  }
+  for (const [section, expectedKeys] of baseKeys) {
+    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 (requireExampleDefaults) {
+      for (const { key, value } of entries) {
+        if (value !== exampleValues.get(key)) throw new Error(`${relativeTarget} must keep the standard default for ${key}`);
+      }
+    }
+  }
+  const actualDeploymentKeys = sections.get('部署').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(({ value }) => value !== '')) {
+    throw new Error(`${relativeTarget} deployment example values must be empty`);
+  }
+  return {
+    extended: actualDeploymentKeys.length === deploymentKeys.length,
+    nonDeploymentKeys: [...seenKeys].filter((key) => !deploymentKeys.includes(key)),
+  };
+}
+
+function extendDeploymentSection(text) {
+  return `${text.trimEnd()}\n${deploymentKeys.map((key) => `${key}=`).join('\n')}\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}`);
+  }
+}
+if (!mode || targetArgument === undefined || (force && mode !== 'write')) {
+  throw new Error('Usage: generate-deployment-files.mjs --target <project-root> (--write [--force] | --check)');
+}
+
+const targetRoot = resolve(targetArgument);
+const targetStat = await stat(targetRoot);
+if (!targetStat.isDirectory()) throw new Error(`Target project root is not a directory: ${targetRoot}`);
+
+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);
+  environmentPlans.push({
+    target,
+    relativeTarget,
+    expectedMode,
+    existing,
+    nonDeploymentKeys: structure.nonDeploymentKeys,
+    expected: structure.extended ? existing : extendDeploymentSection(existing),
+  });
+}
+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 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);
+  }
+}
+
+if (mode === 'write' && differences.length) {
+  throw new Error(`Refusing to overwrite differing deployment files without --force: ${differences.join(', ')}`);
+}
+
+for (const plan of environmentPlans) {
+  if (plan.existing !== plan.expected) {
+    if (mode === 'check') differences.push(plan.relativeTarget);
+    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;
+      }
+    }
+  } else if (mode === 'write') {
+    await chmod(plan.target, 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`);