@wdyy/skills 0.1.0

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

@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, test } from 'node:test';
+import { spawnSync } from 'node:child_process';
+
+const validator = new URL('./validate-deployment-package.mjs', import.meta.url);
+const temporaryDirectories = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((directory) =>
+      rm(directory, { force: true, recursive: true }),
+    ),
+  );
+});
+
+async function createFiles({ includeRollback = true } = {}) {
+  const directory = await mkdtemp(join(tmpdir(), 'deployment-package-'));
+  temporaryDirectories.push(directory);
+  const deploy = join(directory, 'deploy.sh');
+  const nginx = join(directory, 'nginx.conf');
+  const compose = join(directory, 'compose.yml');
+  await writeFile(
+    deploy,
+    `case "$1" in
+start) version="$2";;
+stop) ;;
+restart) ;;
+status) ;;
+${includeRollback ? 'rollback) version="$2";;' : ''}
+esac
+HEALTH_URL=/health
+VERSION_URL=/version
+database/migrations
+`,
+  );
+  await writeFile(
+    nginx,
+    'location /releases/ { root /srv/app; }\nroot /srv/app/current;\n',
+  );
+  await writeFile(
+    compose,
+    'backend-blue:\nbackend-green:\nINSTANCE_ID: blue\nINSTANCE_ID: green\nLOG_DIR: /logs\n',
+  );
+  return { deploy, nginx, compose };
+}
+
+test('接受版本化前端、蓝绿后端和完整命令', async () => {
+  const files = await createFiles();
+  const result = spawnSync(
+    process.execPath,
+    [validator.pathname, files.deploy, files.nginx, files.compose],
+    { encoding: 'utf8' },
+  );
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /valid deployment package/);
+});
+
+test('缺少 rollback 命令时明确失败', async () => {
+  const files = await createFiles({ includeRollback: false });
+  const result = spawnSync(
+    process.execPath,
+    [validator.pathname, files.deploy, files.nginx, files.compose],
+    { encoding: 'utf8' },
+  );
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /rollback/);
+});

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

@@ -0,0 +1,15 @@
+FROM node:24-bookworm-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-bookworm-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/package.json ./
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+EXPOSE 3000
+CMD ["node", "dist/main.js"]

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

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${PROJECT_NAME:?PROJECT_NAME is required}"
+: "${DATABASE_URL:?DATABASE_URL is required}"
+
+DEPLOY_ROOT="${DEPLOY_ROOT:-/srv/$PROJECT_NAME}"
+COMPOSE_FILE="${COMPOSE_FILE:-$DEPLOY_ROOT/deploy/docker/docker-compose.blue-green.yml}"
+UPSTREAM_FILE="${UPSTREAM_FILE:-$DEPLOY_ROOT/deploy/nginx/backend-active.conf}"
+MIGRATION_RUNNER="${MIGRATION_RUNNER:-$DEPLOY_ROOT/scripts/apply-migrations.sh}"
+BACKEND_IMAGE_PREFIX="${BACKEND_IMAGE_PREFIX:-$PROJECT_NAME-backend}"
+BLUE_PORT="${BLUE_PORT:-3001}"
+GREEN_PORT="${GREEN_PORT:-3002}"
+STATE_DIR="$DEPLOY_ROOT/state"
+ACTIVE_STATE="$STATE_DIR/active.env"
+PREVIOUS_STATE="$STATE_DIR/previous.env"
+INCOMING_DIR="$DEPLOY_ROOT/incoming"
+RELEASES_DIR="$DEPLOY_ROOT/releases"
+
+mkdir -p "$STATE_DIR" "$RELEASES_DIR"
+
+assert_version() {
+  [[ "${1:-}" =~ ^[0-9]{8}-[0-9]{3}$ ]] || {
+    echo "version must match YYYYMMDD-NNN" >&2
+    exit 2
+  }
+}
+
+read_active() {
+  ACTIVE_COLOR=green
+  ACTIVE_VERSION=
+  if [[ -f "$ACTIVE_STATE" ]]; then
+    # shellcheck disable=SC1090
+    source "$ACTIVE_STATE"
+  fi
+}
+
+port_for() {
+  [[ "$1" == blue ]] && printf '%s' "$BLUE_PORT" || printf '%s' "$GREEN_PORT"
+}
+
+switch_traffic() {
+  local color="$1" version="$2" port backup
+  port="$(port_for "$color")"
+  backup="$UPSTREAM_FILE.previous"
+  printf 'upstream backend_active {\n  server 127.0.0.1:%s;\n  keepalive 32;\n}\n' "$port" > "$UPSTREAM_FILE.new"
+  [[ -f "$UPSTREAM_FILE" ]] && cp "$UPSTREAM_FILE" "$backup"
+  mv -f "$UPSTREAM_FILE.new" "$UPSTREAM_FILE"
+  if ! nginx -t || ! nginx -s reload; then
+    if [[ -f "$backup" ]]; then
+      mv -f "$backup" "$UPSTREAM_FILE"
+      nginx -t
+      nginx -s reload
+    fi
+    echo "failed to switch Nginx upstream" >&2
+    return 1
+  fi
+  rm -f "$backup"
+  ln -sfn "releases/$version" "$DEPLOY_ROOT/current.new"
+  mv -Tf "$DEPLOY_ROOT/current.new" "$DEPLOY_ROOT/current"
+}
+
+verify_backend() {
+  local color="$1" version="$2" port health_url version_url actual
+  port="$(port_for "$color")"
+  health_url="http://127.0.0.1:$port/health"
+  version_url="http://127.0.0.1:$port/version"
+  HEALTH_URL="$health_url"
+  VERSION_URL="$version_url"
+  curl --fail --silent --show-error --retry 12 --retry-delay 2 "$HEALTH_URL"
+  actual="$(curl --fail --silent --show-error "$VERSION_URL")"
+  [[ "$actual" == "$version" ]] || {
+    echo "backend version mismatch: expected $version, got $actual" >&2
+    exit 1
+  }
+}
+
+start_version() {
+  local version="$1" source_dir release_dir target_color image
+  assert_version "$version"
+  source_dir="$INCOMING_DIR/$version"
+  release_dir="$RELEASES_DIR/$version"
+  [[ -f "$source_dir/frontend.tar.gz" ]] || { echo "missing frontend.tar.gz" >&2; exit 1; }
+  [[ -f "$source_dir/backend-image.tar" ]] || { echo "missing backend-image.tar" >&2; exit 1; }
+  [[ -d "$source_dir/database/migrations" ]] || { echo "missing database/migrations" >&2; exit 1; }
+
+  rm -rf "$release_dir"
+  mkdir -p "$release_dir"
+  if tar -tzf "$source_dir/frontend.tar.gz" | grep -Eq '(^/|(^|/)\.\.(/|$))'; then
+    echo "frontend archive contains an unsafe path" >&2
+    exit 1
+  fi
+  tar -xzf "$source_dir/frontend.tar.gz" -C "$release_dir"
+  [[ -f "$release_dir/index.html" ]] || { echo "frontend release missing index.html" >&2; exit 1; }
+  grep -q "/releases/$version/" "$release_dir/index.html" || {
+    echo "frontend assets are not built with the versioned release URL" >&2
+    exit 1
+  }
+  docker load -i "$source_dir/backend-image.tar"
+  image="$BACKEND_IMAGE_PREFIX:$version"
+  docker image inspect "$image" >/dev/null
+  MIGRATIONS_DIR="$source_dir/database/migrations" "$MIGRATION_RUNNER"
+
+  read_active
+  target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
+  if [[ "$target_color" == blue ]]; then
+    BACKEND_BLUE_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-blue
+  else
+    BACKEND_GREEN_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-green
+  fi
+  verify_backend "$target_color" "$version"
+  [[ -f "$ACTIVE_STATE" ]] && cp "$ACTIVE_STATE" "$PREVIOUS_STATE"
+  switch_traffic "$target_color" "$version"
+  printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$version" > "$ACTIVE_STATE"
+}
+
+restart_current() {
+  read_active
+  [[ -n "$ACTIVE_VERSION" ]] || { echo "no active version" >&2; exit 1; }
+  local target_color image
+  target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
+  image="$BACKEND_IMAGE_PREFIX:$ACTIVE_VERSION"
+  if [[ "$target_color" == blue ]]; then
+    BACKEND_BLUE_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-blue
+  else
+    BACKEND_GREEN_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-green
+  fi
+  verify_backend "$target_color" "$ACTIVE_VERSION"
+  switch_traffic "$target_color" "$ACTIVE_VERSION"
+  printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$ACTIVE_VERSION" > "$ACTIVE_STATE"
+}
+
+rollback_version() {
+  local version="$1"
+  assert_version "$version"
+  [[ -f "$PREVIOUS_STATE" ]] || { echo "no previous deployment" >&2; exit 1; }
+  # shellcheck disable=SC1090
+  source "$PREVIOUS_STATE"
+  [[ "$ACTIVE_VERSION" == "$version" ]] || { echo "rollback target is not the retained previous version" >&2; exit 1; }
+  verify_backend "$ACTIVE_COLOR" "$ACTIVE_VERSION"
+  switch_traffic "$ACTIVE_COLOR" "$ACTIVE_VERSION"
+  cp "$ACTIVE_STATE" "$PREVIOUS_STATE.tmp"
+  cp "$PREVIOUS_STATE" "$ACTIVE_STATE"
+  mv "$PREVIOUS_STATE.tmp" "$PREVIOUS_STATE"
+}
+
+case "${1:-}" in
+  start)
+    version="$2"
+    start_version "$version"
+    ;;
+  stop)
+    docker compose -f "$COMPOSE_FILE" down
+    ;;
+  restart)
+    restart_current
+    ;;
+  status)
+    read_active
+    printf 'color=%s\nversion=%s\n' "$ACTIVE_COLOR" "$ACTIVE_VERSION"
+    docker compose -f "$COMPOSE_FILE" ps
+    ;;
+  rollback)
+    version="$2"
+    rollback_version "$version"
+    ;;
+  *)
+    echo "usage: ./deploy.sh start <version>|stop|restart|status|rollback <version>" >&2
+    exit 2
+    ;;
+esac

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

@@ -0,0 +1,34 @@
+services:
+  backend-blue:
+    image: ${BACKEND_BLUE_IMAGE:-backend-blue:not-configured}
+    env_file: ../../.env.production
+    environment:
+      INSTANCE_ID: blue
+      LOG_DIR: /var/log/application
+    ports:
+      - "127.0.0.1:${BLUE_PORT:-3001}:3000"
+    volumes:
+      - ${HOST_LOG_DIR:?set HOST_LOG_DIR}/backend/blue:/var/log/application
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 6
+
+  backend-green:
+    image: ${BACKEND_GREEN_IMAGE:-backend-green:not-configured}
+    env_file: ../../.env.production
+    environment:
+      INSTANCE_ID: green
+      LOG_DIR: /var/log/application
+    ports:
+      - "127.0.0.1:${GREEN_PORT:-3002}:3000"
+    volumes:
+      - ${HOST_LOG_DIR:?set HOST_LOG_DIR}/backend/green:/var/log/application
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 6

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

@@ -0,0 +1,26 @@
+include /srv/<project>/deploy/nginx/backend-active.conf;
+
+server {
+  location /api/ {
+    proxy_pass http://backend_active;
+    proxy_set_header X-Trace-Id $request_id;
+  }
+
+  location /releases/ {
+    root /srv/<project>;
+    try_files $uri =404;
+  }
+
+  location / {
+    root /srv/<project>/current;
+    try_files $uri $uri/ /index.html;
+  }
+
+  location = /index.html {
+    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;
+  }
+}

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

@@ -0,0 +1,60 @@
+---
+name: wdyy-internal-api-standard
+description: 规范企业内部 REST API 客户端的认证头、traceId、超时、受控重试、熔断、错误映射、日志和响应校验。Use when DEFINE 阶段识别接口边界、BUILD 阶段调用内部服务或 REVIEW 阶段发现散落 fetch、axios、httpClient 调用时。
+---
+
+# 企业内部接口规范
+
+## Overview
+
+将内部服务调用收敛到可追踪、可验证且有明确失败语义的 REST 客户端边界。
+
+## When to Use
+
+- 识别接口边界、实现内部服务调用或审查业务层 HTTP 调用时。
+
+## 协作边界
+
+先确认接口契约、错误语义、实现计划和测试要求。本 skill 独立规定企业客户端实现约束，不能替代实现和验证工作。
+
+## 输入与输出
+
+- 输入：接口契约、认证方案、超时预算、错误码、重试安全性和 Mock 场景。
+- 输出：统一客户端、接口定义、错误处理、Mock 与测试证据。
+- 使用 [客户端模板](templates/api-client.template.ts)、[错误模板](templates/api-error.template.ts) 和 [规则](reference/internal-api-rules.md)。
+
+## 执行步骤
+
+1. 确认服务边界、认证头、请求/响应 schema、超时预算及幂等条件。
+2. 通过唯一封装客户端发起所有内部调用，注入 traceId 和请求日志。
+3. 仅对明确幂等且可恢复的错误执行有限重试；配置熔断与可观测错误码。
+4. 校验响应结构，映射外部错误为业务可处理的稳定错误。
+5. 用 Mock 覆盖超时、认证失败、无效响应、重试和熔断路径。
+
+## 禁止事项
+
+- 不得在业务代码中散落 `fetch`、`axios` 或原始 `httpClient` 调用。
+- 不得对非幂等写操作无条件重试。
+- 不得吞掉响应校验、超时、错误码或调用日志。
+
+## Red Flags
+
+- 业务模块直接调用 fetch、axios 或原始 httpClient。
+- 未定义幂等性却配置重试，或未校验响应结构。
+
+## Verification
+
+- [ ] 调用均通过封装客户端，traceId 与认证头可验证。
+- [ ] 超时、重试上限、熔断与错误码映射有测试。
+- [ ] 无效响应不能进入业务逻辑。
+- [ ] Mock 覆盖成功及主要异常分支。
+
+认证、幂等性或错误语义未定义时，停止调用实现并回到接口契约澄清；不得以无限重试或吞错替代决策。
+
+## Common Rationalizations
+
+| 合理化说法 | 事实 |
+|---|---|
+| “一个 fetch 不值得封装” | 分散调用无法统一认证、追踪、超时和错误行为。 |
+| “重试总会提高成功率” | 非幂等重试会造成重复写入和状态污染。 |
+| “内部服务可以信任响应” | 服务边界仍可能发生版本漂移和故障。 |

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Enterprise Internal API Standard"
+  short_description: "Standardize internal REST client integrations"
+  default_prompt: "Use $wdyy-internal-api-standard to implement an internal REST API client."

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

@@ -0,0 +1,5 @@
+# 内部 API 规则
+
+- 认证头、`x-trace-id`、超时、响应 schema 与错误码映射均由统一客户端处理。
+- 仅明确幂等请求可有限重试；熔断状态必须可观测。
+- 禁止业务层直接调用 fetch、axios 或原始 httpClient。

package/.well-known/skills/wdyy-internal-api-standard/scripts/check-raw-http-calls.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+
+const file = process.argv[2];
+if (!file) throw new Error('Pass a business source file');
+const content = await readFile(file, 'utf8');
+if (/\b(fetch|axios\.|httpClient\.)\s*\(/.test(content)) {
+  throw new Error(`Raw HTTP call found in ${file}; use the internal API client`);
+}
+process.stdout.write('no raw HTTP calls\n');

package/.well-known/skills/wdyy-internal-api-standard/templates/api-client.template.ts

@@ -0,0 +1,20 @@
+type RequestOptions = { method: string; path: string; body?: unknown; traceId: string; idempotent?: boolean };
+
+export class InternalApiClient {
+  constructor(private readonly baseUrl: string, private readonly token: () => Promise<string>) {}
+
+  async request<T>(options: RequestOptions): Promise<T> {
+    const response = await fetch(`${this.baseUrl}${options.path}`, {
+      method: options.method,
+      headers: {
+        authorization: `Bearer ${await this.token()}`,
+        'content-type': 'application/json',
+        'x-trace-id': options.traceId,
+      },
+      body: options.body === undefined ? undefined : JSON.stringify(options.body),
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!response.ok) throw new Error(`INTERNAL_API_${response.status}`);
+    return await response.json() as T;
+  }
+}

package/.well-known/skills/wdyy-internal-api-standard/templates/api-error.template.ts

@@ -0,0 +1,7 @@
+export class InternalApiError extends Error {
+  constructor(
+    readonly code: string,
+    readonly retryable: boolean,
+    message: string,
+  ) { super(message); }
+}

package/.well-known/skills/wdyy-internal-api-standard/templates/api-mock.template.ts

@@ -0,0 +1,8 @@
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  http.get('*/internal/<resource>', ({ request }) => {
+    if (!request.headers.get('x-trace-id')) return HttpResponse.json({ code: 'TRACE_ID_REQUIRED' }, { status: 400 });
+    return HttpResponse.json({ data: [] });
+  }),
+];

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

@@ -0,0 +1,65 @@
+---
+name: wdyy-logging-standard
+description: 为 NestJS 和 Vue 项目实现前端异常上报、后端统一结构化 JSON 日志、蓝绿实例隔离、traceId 传递、敏感信息脱敏与 2MB 文件轮转。Use when 编写日志、错误处理、前端异常上报或审查生产可观测性时。
+---
+
+# 企业日志规范
+
+## Overview
+
+建立可追踪、脱敏、可轮转的结构化日志，以支撑运行时排障而不泄露敏感信息。
+
+## When to Use
+
+- 编写业务日志、错误处理、接口中间件或进行可观测性审查时。
+
+## 协作边界
+
+日志实现必须纳入可观测性、实现计划和测试验证。本 skill 独立规定企业字段与隐私边界，不能降低 RED 指标、追踪或告警要求。
+
+## 输入与输出
+
+- 输入：服务名、实例标识、环境、请求上下文、敏感字段清单、`LOG_DIR`。
+- 输出：统一 logger、前端异常上报客户端、HTTP 日志中间件、脱敏规则和日志验证结果。
+- 使用 [日志规则](reference/logging-rules.md) 和 [logger 模板](templates/logger.template.ts)。
+
+## 执行步骤
+
+1. 定义 `timestamp`、`level`、`service`、`instanceId`、`env`、`traceId`、`userId`、`method`、`path`、`query`、`body`、`statusCode`、`result`、`durationMs`、`errorCode`、`message`、`params` 的最小 JSON 契约。`timestamp` 必须为服务器本地时间 `YYYY-MM-DD HH:mm:ss`，精确到秒。
+2. 在入口生成或透传 traceId；在内部 REST 调用中继续传递。
+3. 统一封装 logger；业务代码不得直接使用 `console.log`。
+4. HTTP 请求日志记录 `query`（查询参数）和 `body`（请求体）；授权请求可记录实际用户、模式、表和权限等入参。`statusCode` 为 100–399 时 `result` 为 `success`，为 400–599 时 `result` 为 `failure`。
+5. password、token、secret、authorization、databaseUrl、idCard、bankCard 为敏感字段，必须连同键和值一起从日志中移除。数组仅保留前 500 项，超出部分追加 `[TRUNCATED N ITEMS]`；拒绝记录未裁剪的大对象。
+6. Vue 捕获未处理异常和 Promise 拒绝，裁剪、脱敏后上报后端；浏览器不得尝试写服务器文件。
+7. 后端按 `LOG_DIR/<service>/<instanceId>/yyyy-mm-dd_hh24-mm-ss.log` 写入，文件名使用服务器本地时间；历史日志不重命名。最新文件超过 2MB 时创建新文件，并测试轮转。
+
+## 禁止事项
+
+- 不得记录秘密、完整敏感身份信息或未裁剪的大请求/响应对象。
+- 不得将 `message` 仅限制为 `success` 或 `error`。
+- 不得用 console 输出替代业务日志。
+
+## Red Flags
+
+- 业务代码直接调用 console，或日志包含未脱敏的凭证、身份信息。
+- 请求日志缺失 traceId、状态码或耗时。
+- 蓝绿容器共享同一日志文件，或前端异常未进入统一后端日志。
+
+## Verification
+
+- [ ] 正常、异常和 HTTP 请求日志均为可解析 JSON。
+- [ ] traceId 跨入口与内部调用可追踪。
+- [ ] 敏感字段移除、数组截断、HTTP 入参与状态结果映射均有测试覆盖，轮转阈值可验证。
+- [ ] 前端异常上报经过裁剪、脱敏和后端身份校验。
+- [ ] 蓝绿实例使用独立日志目录，容器替换后日志仍保留。
+- [ ] `LOG_DIR` 缺失或不可写时服务以明确错误停止。
+
+无法确定某字段是否敏感时按敏感处理并要求数据负责人确认；不得先原样记录再补救。
+
+## Common Rationalizations
+
+| 合理化说法 | 事实 |
+|---|---|
+| “开发日志不用脱敏” | 开发日志同样会被共享和长期保留。 |
+| “console.log 足够定位问题” | 无统一字段、轮转和 traceId 的输出不能支撑运维。 |
+| “完整请求最方便排查” | 便利不构成暴露隐私和大对象的理由。 |

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Enterprise Logging Standard"
+  short_description: "Implement instance-safe logs and frontend error reporting"
+  default_prompt: "Use $wdyy-logging-standard to implement frontend error reporting and instance-isolated structured logs."

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

@@ -0,0 +1,12 @@
+# 日志规则
+
+- 日志为一行 JSON，最小字段见 `logger.template.ts`。
+- `timestamp` 使用服务器本地时间 `YYYY-MM-DD HH:mm:ss`，精确到秒；不得包含毫秒、`T` 或 `Z`。
+- 文件名使用服务器本地时间 `yyyy-mm-dd_hh24-mm-ss.log`；当前文件大于 2MB 时先创建新文件再写入。既有日志文件不得重命名。
+- 日志仅记录关键业务事件、请求摘要和异常；`params`、`query` 和 `body` 必须裁剪。授权请求可记录实际用户、模式、表和权限等入参。
+- HTTP 日志必须保留 `statusCode`，且 `result` 在 100–399 时为 `success`、在 400–599 时为 `failure`。
+- password、token、secret、authorization、databaseUrl、idCard、bankCard 必须从输出中完全移除，不得以占位符输出。数组保留前 500 项；超出时追加 `[TRUNCATED N ITEMS]`。
+- HTTP 入口和内部服务调用必须透传 traceId。
+- 每条日志必须包含 `instanceId`；生产蓝绿容器分别写入 `LOG_DIR/<service>/<instanceId>/`，不得并发写同一文件。
+- Vue 未处理异常和 Promise 拒绝必须裁剪、脱敏后上报后端；后端校验请求身份和大小后写入统一日志。
+- 日志目录必须挂载到容器外部持久路径，替换容器不得删除历史日志。

package/.well-known/skills/wdyy-logging-standard/scripts/validate-log-entry.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+
+const entry = JSON.parse(await readFile(process.argv[2], 'utf8'));
+const required = ['timestamp', 'level', 'service', 'instanceId', 'env', 'message'];
+const missing = required.filter((key) => !(key in entry));
+if (missing.length) throw new Error('Missing log fields: ' + missing.join(', '));
+if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(entry.timestamp)) {
+  throw new Error('timestamp must use local YYYY-MM-DD HH:mm:ss format');
+}
+
+const sensitiveKeys = new Set([
+  'password', 'token', 'secret', 'authorization', 'databaseurl', 'idcard', 'bankcard',
+]);
+const validateValue = (value) => {
+  if (Array.isArray(value)) {
+    if (value.length > 500 && (value.length !== 501 || !/^\[TRUNCATED \d+ ITEMS\]$/.test(value.at(-1)))) {
+      throw new Error('Arrays over 500 items must end with a truncation marker');
+    }
+    value.forEach(validateValue);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [key, item] of Object.entries(value)) {
+    if (sensitiveKeys.has(key.toLowerCase())) throw new Error('Sensitive fields must be omitted');
+    validateValue(item);
+  }
+};
+validateValue(entry);
+
+if ('statusCode' in entry) {
+  const expected = entry.statusCode >= 100 && entry.statusCode <= 399 ? 'success'
+    : entry.statusCode >= 400 && entry.statusCode <= 599 ? 'failure' : undefined;
+  if (!expected || entry.result !== expected) throw new Error('statusCode and result must match');
+}
+process.stdout.write('valid log entry\n');