@wdyy/skills 0.1.7 → 0.1.9

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

@@ -25,6 +25,7 @@ description: 基于标准五段根 .env，为无 CI/CD 的多项目 Linux 服务
 - 宿主机 Nginx 只监听根 `.env` 的 `PROJECT_HTTP_PORT`，`/api/` 代理活动后端，其他请求代理活动前端。
 - 所有容器只把项目根 `./logs` 挂载到 `/app/logs`；日志文件直接位于 `logs/`，不得创建服务、颜色或日期子目录。
 - 根 `.env` 原样复制到 `deploy/.env` 并人工上传，但必须被 `.dockerignore` 排除，且不得进入版本目录或任一镜像。
+- `FRONTEND_BASE_IMAGE` 与 `BACKEND_BASE_IMAGE` 使用非空 Docker 镜像引用；可直接使用本地带标签镜像。相同标签在不同时间重新构建时可能对应不同基础镜像内容，但已导出的项目成品镜像仍按版本确定部署。
 - 环境文件固定按“前端、后端、数据库、API、部署”排列；部署生成器保留前四段和已有值，只扩充部署段。
 - `DATABASE_MIGRATION_MODE=manual` 时只打包迁移与执行脚本；`none` 时不要求数据库文件。任何部署命令都不得自动访问数据库。
 - 相同输入生成的 deploy.sh、Compose、Nginx 配置必须字节一致；版本指针、镜像归档和 manifest 可随发布变化。

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

@@ -40,14 +40,14 @@ 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>
+FRONTEND_BASE_IMAGE=nginx:stable
+BACKEND_BASE_IMAGE=node:24-alpine3.24
 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` 实际值，不得保留占位符或示例部署端口。`PROJECT_NAME` 只允许 `^[a-z][a-z0-9_]*$`。所有宿主机端口必须互不相同且在 1–65535；两个基础镜像必须是非空 Docker 镜像引用，可使用本地带标签镜像。相同标签在不同时间重新构建时可能解析为不同基础镜像内容；成功构建后导出的项目成品镜像仍用于服务器端确定部署。数据库连接键允许为空，但项目使用数据库时必须填写真实值。
 
 `.env` 权限必须为 `0600` 或只读的 `0400`。部署脚本只把明确的部署键载入自身环境；数据库密码、JWT 等其他应用键保留在文件中供 Compose 注入容器，不得改变脚本的 `PATH`、Shell 选项或命令行为。
 

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

@@ -129,9 +129,6 @@ if (!/^\/.+[^/]$/.test(env.get('SERVER_PROJECTS_ROOT'))) throw new Error('Invali
 for (const key of ['FRONTEND_URL', 'BACKEND_URL', 'DOCKER_BIND_IP']) {
   if (!/^[A-Za-z0-9:.%-]+$/.test(env.get(key))) throw new Error(`${key} contains unsafe characters`);
 }
-for (const key of ['FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE']) {
-  if (!/@sha256:[0-9a-f]{64}$/.test(env.get(key))) throw new Error(`${key} must be pinned by digest`);
-}
 const migrationMode = env.get('DATABASE_MIGRATION_MODE');
 if (!['manual', 'none'].includes(migrationMode)) throw new Error('DATABASE_MIGRATION_MODE must be manual or none');
 if (env.has('LOG_DIR') || env.has('HOST_LOG_DIR')) throw new Error('Root .env must not configure log directories');

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

@@ -60,8 +60,8 @@ FRONTEND_BLUE_PORT=19091
 FRONTEND_GREEN_PORT=19092
 BACKEND_BLUE_PORT=19093
 BACKEND_GREEN_PORT=19094
-FRONTEND_BASE_IMAGE=nginx@sha256:${'0'.repeat(64)}
-BACKEND_BASE_IMAGE=node@sha256:${'1'.repeat(64)}
+FRONTEND_BASE_IMAGE=nginx:stable
+BACKEND_BASE_IMAGE=node:24-alpine3.24
 DATABASE_MIGRATION_MODE=${mode}
 ${extra}`;
 }
@@ -319,12 +319,11 @@ test('dotenv 被作为数据解析，不执行命令替换或覆盖脚本 PATH',
   await assert.rejects(access(join(fixture.root, 'should-not-exist')));
 });
 
-test('build 拒绝重复键、漂移基础镜像和额外版本参数', async () => {
+test('build 接受带标签基础镜像并拒绝重复键和额外版本参数', async () => {
   const duplicate = await createFixture({ extraEnv: 'PROJECT_NAME=duplicate\n' });
   assert.notEqual(runBuild(duplicate).status, 0);
-  const mutable = await createFixture();
-  await writeFile(join(mutable.root, '.env'), (await readFile(join(mutable.root, '.env'), 'utf8')).replace(/nginx@sha256:[0-9a-f]+/, 'nginx:latest'));
-  assert.notEqual(runBuild(mutable).status, 0);
+  const tagged = await createFixture();
+  assert.equal(runBuild(tagged).status, 0);
   const extra = await createFixture();
   assert.equal(runBuild(extra, {}, '20260808-001').status, 2);
   const logDirectory = await createFixture({ extraEnv: 'LOG_DIR=/tmp/logs\n' });

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

@@ -132,10 +132,6 @@ validate_configuration() {
     [[ "$seen" != *" $port "* ]] || fail "host ports must be unique; duplicate value: $port"
     seen+="$port "
   done
-  [[ "$FRONTEND_BASE_IMAGE" =~ @sha256:[0-9a-f]{64}$ ]] ||
-    fail "FRONTEND_BASE_IMAGE must be pinned by sha256 digest"
-  [[ "$BACKEND_BASE_IMAGE" =~ @sha256:[0-9a-f]{64}$ ]] ||
-    fail "BACKEND_BASE_IMAGE must be pinned by sha256 digest"
   [[ "$DATABASE_MIGRATION_MODE" == manual || "$DATABASE_MIGRATION_MODE" == none ]] ||
     fail "DATABASE_MIGRATION_MODE must be manual or none"
 }

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

@@ -25,6 +25,6 @@ FRONTEND_BLUE_PORT=
 FRONTEND_GREEN_PORT=
 BACKEND_BLUE_PORT=
 BACKEND_GREEN_PORT=
-FRONTEND_BASE_IMAGE=
-BACKEND_BASE_IMAGE=
+FRONTEND_BASE_IMAGE=nginx:stable
+BACKEND_BASE_IMAGE=node:24-alpine3.24
 DATABASE_MIGRATION_MODE=

package/README.md

@@ -60,7 +60,51 @@ wdyy update-skill --all
 
 ## 发布到 npm
 
-发布包名为 `@wdyy/skills`，命令行入口为 `wdyy`。发布前不得跳过验证：
+发布包名为 `@wdyy/skills`，命令行入口为 `wdyy`。以下流程适用于首次发布和后续发版；同一包名与版本只能发布一次。
+
+### 使用发布脚本
+
+推荐从项目根目录手动运行 `release_npm.sh`。脚本会检查工作区、组织权限、项目测试、lint 与打包内容，自动执行 `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/package.json

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