@wdyy/skills 0.1.6 → 0.1.8

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

@@ -1,36 +1,70 @@
 services:
+  frontend-blue:
+    image: ${FRONTEND_IMAGE:?FRONTEND_IMAGE is required}
+    env_file: ../../.env
+    environment:
+      INSTANCE_ID: blue
+      NGINX_ENVSUBST_FILTER: "^(INSTANCE_ID|FRONTEND_URL|FRONTEND_PORT|RELEASE_VERSION)$"
+    ports:
+      - "${DOCKER_BIND_IP}:${FRONTEND_BLUE_PORT}:${FRONTEND_PORT}"
+    volumes:
+      - ../../logs:/app/logs
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "probe_host=$${FRONTEND_URL}; [ \"$${probe_host}\" != 0.0.0.0 ] || probe_host=127.0.0.1; wget -qO- \"http://$${probe_host}:$${FRONTEND_PORT}/health\""]
+      interval: 10s
+      timeout: 3s
+      retries: 6
+
   backend-blue:
-    image: ${BACKEND_BLUE_IMAGE:-backend-blue:not-configured}
-    env_file: ../../.env.production
+    image: ${BACKEND_IMAGE:?BACKEND_IMAGE is required}
+    env_file: ../../.env
     environment:
       INSTANCE_ID: blue
-      HOST: ${BACKEND_LISTEN_HOST}
-      PORT: ${BACKEND_CONTAINER_PORT}
+      HOST: ${BACKEND_URL}
+      PORT: ${BACKEND_PORT}
+    ports:
+      - "${DOCKER_BIND_IP}:${BACKEND_BLUE_PORT}:${BACKEND_PORT}"
+    volumes:
+      - ../../logs:/app/logs
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "probe_host=$${BACKEND_URL}; [ \"$${probe_host}\" != 0.0.0.0 ] || probe_host=127.0.0.1; wget -qO- \"http://$${probe_host}:$${BACKEND_PORT}/health\""]
+      interval: 10s
+      timeout: 3s
+      retries: 6
+
+  frontend-green:
+    image: ${FRONTEND_IMAGE:?FRONTEND_IMAGE is required}
+    env_file: ../../.env
+    environment:
+      INSTANCE_ID: green
+      NGINX_ENVSUBST_FILTER: "^(INSTANCE_ID|FRONTEND_URL|FRONTEND_PORT|RELEASE_VERSION)$"
     ports:
-      - "${BACKEND_BIND_IP}:${BLUE_PORT}:${BACKEND_CONTAINER_PORT}"
+      - "${DOCKER_BIND_IP}:${FRONTEND_GREEN_PORT}:${FRONTEND_PORT}"
     volumes:
       - ../../logs:/app/logs
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "wget", "-qO-", "${BACKEND_CONTAINER_HEALTH_URL}"]
+      test: ["CMD-SHELL", "probe_host=$${FRONTEND_URL}; [ \"$${probe_host}\" != 0.0.0.0 ] || probe_host=127.0.0.1; wget -qO- \"http://$${probe_host}:$${FRONTEND_PORT}/health\""]
       interval: 10s
       timeout: 3s
       retries: 6
 
   backend-green:
-    image: ${BACKEND_GREEN_IMAGE:-backend-green:not-configured}
-    env_file: ../../.env.production
+    image: ${BACKEND_IMAGE:?BACKEND_IMAGE is required}
+    env_file: ../../.env
     environment:
       INSTANCE_ID: green
-      HOST: ${BACKEND_LISTEN_HOST}
-      PORT: ${BACKEND_CONTAINER_PORT}
+      HOST: ${BACKEND_URL}
+      PORT: ${BACKEND_PORT}
     ports:
-      - "${BACKEND_BIND_IP}:${GREEN_PORT}:${BACKEND_CONTAINER_PORT}"
+      - "${DOCKER_BIND_IP}:${BACKEND_GREEN_PORT}:${BACKEND_PORT}"
     volumes:
       - ../../logs:/app/logs
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "wget", "-qO-", "${BACKEND_CONTAINER_HEALTH_URL}"]
+      test: ["CMD-SHELL", "probe_host=$${BACKEND_URL}; [ \"$${probe_host}\" != 0.0.0.0 ] || probe_host=127.0.0.1; wget -qO- \"http://$${probe_host}:$${BACKEND_PORT}/health\""]
       interval: 10s
       timeout: 3s
       retries: 6

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

@@ -13,3 +13,5 @@ logs/
 node_modules/
 venv/
 .pnpm-store/
+.deploy-build.lock/
+.deploy-build.*

package/.well-known/skills/wdyy-deployment-standard/templates/env.example.template

@@ -0,0 +1,30 @@
+# 前端
+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=
+
+# API
+
+# 部署
+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=

package/.well-known/skills/wdyy-deployment-standard/templates/frontend-container.conf.template

@@ -0,0 +1,24 @@
+server {
+  listen ${FRONTEND_URL}:${FRONTEND_PORT};
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+  access_log /app/logs/frontend-${INSTANCE_ID}-access.log;
+  error_log /app/logs/frontend-${INSTANCE_ID}-error.log warn;
+
+  location = /health {
+    access_log off;
+    default_type text/plain;
+    return 200 'ok';
+  }
+
+  location = /version {
+    access_log off;
+    default_type text/plain;
+    return 200 '${RELEASE_VERSION}';
+  }
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

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

@@ -0,0 +1,7 @@
+ARG FRONTEND_BASE_IMAGE
+FROM ${FRONTEND_BASE_IMAGE}
+ARG RELEASE_VERSION
+ENV RELEASE_VERSION=${RELEASE_VERSION}
+LABEL org.opencontainers.image.version=${RELEASE_VERSION}
+COPY src/frontend/dist/ /usr/share/nginx/html/
+COPY scripts/deployment/frontend-container.conf.template /etc/nginx/templates/default.conf.template

package/.well-known/skills/wdyy-deployment-standard/templates/nginx-upstream.template.conf

@@ -1,27 +1,26 @@
-include "__DEPLOY_ROOT__/nginx/backend-active.conf";
+# wdyy-project: __PROJECT_NAME__
+# wdyy-port: __PROJECT_HTTP_PORT__
+# wdyy-docker-ports: __DOCKER_HOST_PORTS__
+include "__DEPLOY_ROOT__/nginx/active-upstreams.conf";
 
 server {
+  listen __PROJECT_HTTP_PORT__;
+  server_name _;
+
   location /api/ {
-    proxy_pass __BACKEND_PROXY_URL__;
+    proxy_pass http://__BACKEND_UPSTREAM_NAME__;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
     proxy_set_header X-Trace-Id $request_id;
   }
 
-  location /releases/ {
-    root "__DEPLOY_ROOT__";
-    try_files $uri =404;
-  }
-
   location / {
-    root "__DEPLOY_ROOT__/current";
-    try_files $uri $uri/ /index.html;
-  }
-
-  location = /index.html {
-    root "__DEPLOY_ROOT__/current";
-    add_header Cache-Control "no-cache, no-store, must-revalidate" always;
-  }
-
-  location ~* ^/releases/.+\.(?:js|css|woff2?|png|jpg|svg)$ {
-    add_header Cache-Control "public, max-age=31536000, immutable" always;
+    proxy_pass http://__FRONTEND_UPSTREAM_NAME__;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
   }
 }

package/README.md

@@ -18,7 +18,7 @@ OpenSpec                           单项变更的需求、设计、任务、实
 | `wdyy-api-standard` | 根据“获取XX数据”“使用XX接口”等需求定位接口 reference，并按已确认契约写入调用方式。 |
 | `wdyy-bug-record` | 手动汇总当前任务已解决的问题，并按模板追加至 `docs/bug_record.md`。 |
 | `wdyy-logging-standard` | 结构化日志、敏感字段移除、traceId、前端异常上报与日志轮转。 |
-| `wdyy-deployment-standard` | 人工 SCP 交付、版本化前端资源、Docker 蓝绿发布与回滚。 |
+| `wdyy-deployment-standard` | 扩充标准五段环境配置，生成人工交付、双 Docker 蓝绿发布与回滚文件。 |
 
 ## 使用方式
 
@@ -29,7 +29,7 @@ npm install -g @wdyy/skills
 wdyy init
 ```
 
-`wdyy init` 会在系统用户目录 `.agents/skills/` 安装或更新 5 个受管理 Skill，不在目标项目创建 `.agents/skills/`。它还会执行 `git init`，创建或补齐 `.gitignore` 的 `.env`、`node_modules/`、`venv/`、`.pnpm-store/`、`logs/`、`dist/`、`.DS_Store`、`*.tar.gz` 规则，创建 `src/frontend`、`src/backend`、`database`、`deploy`、`docs`、`scripts`、`tests` 和空 `.env.example`，并执行 `openspec init`、创建或追加 `docs/bug_record.md` 模板。若目标项目已有 `AGENTS.md`，原文件保持不变，命令将生成 `AGENTS_new.md`。
+`wdyy init` 会在系统用户目录 `.agents/skills/` 安装或更新 5 个受管理 Skill，不在目标项目创建 `.agents/skills/`。它还会执行 `git init`，创建或补齐 `.gitignore` 的 `.env`、`node_modules/`、`venv/`、`.pnpm-store/`、`logs/`、`dist/`、`.DS_Store`、`*.tar.gz` 规则，创建 `src/frontend`、`src/backend`、`database`、`deploy`、`docs`、`scripts`、`tests`，并以相同的“前端、后端、数据库、API、部署”结构创建缺失的 `.env` 与 `.env.example`。默认前端监听 `0.0.0.0:5173`、后端监听 `0.0.0.0:3000`、数据库端口为 `5432`；已有环境文件保持不变。随后命令执行 `openspec init`、创建或追加 `docs/bug_record.md` 模板。若目标项目已有 `AGENTS.md`，原文件保持不变，命令将生成 `AGENTS_new.md`。
 
 ### 仅更新已安装的 Skill
 
@@ -60,7 +60,51 @@ wdyy update-skill --all
 
 ## 发布到 npm
 
-发布包名为 `@wdyy/skills`，命令行入口为 `wdyy`。发布前不得跳过验证：
+发布包名为 `@wdyy/skills`，命令行入口为 `wdyy`。以下流程适用于首次发布和后续发版；同一包名与版本只能发布一次。
+
+### 使用发布脚本
+
+推荐从项目根目录手动运行 `release_npm.sh`。脚本会检查工作区、组织权限和全部质量校验，自动执行 `npm version <patch|minor|major>`、`npm publish --access public`，并核验 registry 版本。它不会执行登录、浏览器认证或处理认证凭据。
+
+首次运行或登录失效时，先手工登录；脚本检测到未登录也会提示并退出：
+
+```bash
+npm login
+./release_npm.sh patch
+```
+
+可按变更范围选择版本级别：
+
+```bash
+./release_npm.sh patch # 修复或小幅调整
+./release_npm.sh minor # 向后兼容的新功能
+./release_npm.sh major # 不兼容变更
+```
+
+脚本在 `npm publish` 成功前不会推送 Git 提交或标签；若 `npm version` 已完成而后续发布失败，工程师必须根据 npm 与 Git 的实际状态处理，不得重复发布相同版本。
+
+### 手工执行的发布流程
+
+当需要排查发布问题时，可按以下步骤手工执行。发布前确认当前工作区只包含准备发布的内容，并查看将要发布的版本：
+
+### 1. 准备发布内容
+
+```bash
+git status --short
+node -p "require('./package.json').version"
+```
+
+后续发版先选择符合变更范围的版本级别。`npm version` 会更新 `package.json`，并在 Git 工作区满足其要求时创建提交和标签：
+
+```bash
+npm version patch # 修复或小幅调整
+# npm version minor # 向后兼容的新功能
+# npm version major # 不兼容变更
+```
+
+### 2. 执行发布前校验
+
+版本确定后，必须完整执行以下校验，不得跳过：
 
 ```bash
 npm test
@@ -69,27 +113,31 @@ node --test $(find .well-known/skills -path '*/scripts/*.test.mjs' -print)
 npm pack --dry-run
 ```
 
-首次发布前，登录拥有 `wdyy` 组织 owner 或发布权限的 npm 账号，并在 npm 账户设置中配置安全密钥 2FA（WebAuthn，例如 macOS Touch ID 或硬件安全密钥）。npm 已不支持通过 CLI 新增 TOTP 认证器；不得在仓库、终端历史或文档中记录 access token、验证码或恢复码。
+其中 `npm pack --dry-run` 用于确认包内容；应包含 `bin`、`lib`、`.well-known/skills` 与 `README.md`，且不应包含本地环境文件或其他无关文件。
 
-确认身份与组织权限后，发布公开包：
+### 3. 登录并核对组织权限
+
+首次发布前，在 npm 账户设置中配置安全密钥 2FA（WebAuthn，例如 macOS Touch ID 或硬件安全密钥）。npm 已不支持通过 CLI 新增 TOTP 认证器。使用拥有 `wdyy` 组织 Owner 或发布权限的账号登录，并核对身份和组织成员资格：
 
 ```bash
 npm login
 npm whoami
 npm org ls wdyy
-npm publish --access public
 ```
 
-`npm whoami` 返回 `E401` 表示当前 CLI 没有有效登录态，应重新执行 `npm login` 后再发布。已成功登录但 `npm publish --access public` 仍返回 `E404` 时，通常表示当前账号没有 `@wdyy` 组织的包创建或发布权限；请由该组织的 Owner 授予权限后重试。不要通过在命令行中传入 access token、验证码或恢复码来规避认证。
+不得在仓库、终端历史或文档中记录 access token、验证码或恢复码。
 
-同一包名和版本只能发布一次。后续发布必须先升级版本，再重新执行全部发布前验证：
+### 4. 发布公开包
+
+完成校验且确认登录态、组织权限和版本号无误后，执行：
 
 ```bash
-npm version patch
 npm publish --access public
 ```
 
-发布后核验 registry 中的版本，并在干净的目标项目中验证全局安装与初始化：
+### 5. 发布后验收
+
+核对 registry 已出现目标版本；然后在干净的目标项目中安装并验证初始化：
 
 ```bash
 npm view @wdyy/skills version
@@ -97,6 +145,14 @@ npm install -g @wdyy/skills
 wdyy init
 ```
 
+### 常见问题
+
+- `npm whoami` 返回 `E401`：当前 CLI 没有有效登录态，重新执行 `npm login` 后再继续。
+- 已成功登录但 `npm publish --access public` 返回 `E404`：通常是当前账号没有 `@wdyy` 组织的包创建或发布权限；请组织 Owner 授权后重试。
+- 发布提示版本已存在：版本不可覆盖，先通过 `npm version patch`、`minor` 或 `major` 生成新版本，再从“执行发布前校验”重新开始。
+
+不得通过在命令行中传入 access token、验证码或恢复码来规避认证或权限问题。
+
 ## 验证
 
 ```bash

package/lib/wdyy-cli.js

@@ -34,7 +34,28 @@ const requiredGitIgnoreEntries = [
   '*.tar.gz'
 ];
 
-const defaultProjectLayout = [...defaultProjectDirectories, '.env.example'];
+const defaultEnvironmentContent = `# 前端
+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=
+
+# API
+
+# 部署
+`;
+
+const defaultProjectLayout = [...defaultProjectDirectories, '.env', '.env.example'];
 
 const generatedAgentsContent = `# 企业开发规则
 
@@ -49,7 +70,7 @@ const generatedAgentsContent = `# 企业开发规则
 
 默认项目目录为 ${defaultProjectLayout.map((path) => `\`${path}\``).join('、')}。
 
-所有 URL、端口和 IP 地址必须从 \`.env\` 文件读取，禁止在代码中硬编码；不得提交秘密或生产环境 \`.env\`。
+所有 URL、端口和 IP 地址必须从项目根目录的 \`.env\` 文件读取，禁止在代码中硬编码；不得提交秘密或生产环境 \`.env\`。
 
 项目开发完成后必须创建 \`README.md\`，内容包括项目技术栈、目录结构和安装部署说明。
 
@@ -158,13 +179,18 @@ async function createDefaultProjectLayout(targetRoot, writtenPaths) {
     if (!existed) writtenPaths.push(destination);
   }
 
-  const envExamplePath = join(targetRoot, '.env.example');
-  try {
-    await access(envExamplePath);
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-    await writeFile(envExamplePath, '', 'utf8');
-    writtenPaths.push(envExamplePath);
+  for (const environmentFile of ['.env', '.env.example']) {
+    const environmentPath = join(targetRoot, environmentFile);
+    try {
+      await access(environmentPath);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      await writeFile(environmentPath, defaultEnvironmentContent, {
+        encoding: 'utf8',
+        mode: environmentFile === '.env' ? 0o600 : 0o644
+      });
+      writtenPaths.push(environmentPath);
+    }
   }
   console.log(`已准备默认项目目录: ${defaultProjectDirectories.join('、')}`);
 }

package/package.json

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