@wdyy/skills 0.1.0

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

@@ -0,0 +1,133 @@
+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-log-entry.mjs', import.meta.url);
+const temporaryDirectories = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((directory) =>
+      rm(directory, { force: true, recursive: true }),
+    ),
+  );
+});
+
+async function validate(entry) {
+  const directory = await mkdtemp(join(tmpdir(), 'log-entry-'));
+  temporaryDirectories.push(directory);
+  const input = join(directory, 'entry.json');
+  await writeFile(input, JSON.stringify(entry));
+  return spawnSync(process.execPath, [validator.pathname, input], { encoding: 'utf8' });
+}
+
+test('蓝绿实例日志必须包含 instanceId', async () => {
+  const result = await validate({
+    timestamp: '2026-07-09 08:00:00',
+    level: 'info',
+    service: 'backend',
+    instanceId: 'blue',
+    env: 'production',
+    message: 'request completed',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+});
+
+test('缺少 instanceId 时明确失败', async () => {
+  const result = await validate({
+    timestamp: '2026-07-09 08:00:00',
+    level: 'info',
+    service: 'backend',
+    env: 'production',
+    message: 'request completed',
+  });
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /instanceId/);
+});
+
+test('HTTP 状态码与 result 不一致时明确失败', async () => {
+  const result = await validate({
+    timestamp: '2026-07-09 08:00:00',
+    level: 'info',
+    service: 'backend',
+    instanceId: 'blue',
+    env: 'production',
+    message: 'request completed',
+    statusCode: 201,
+    result: 'failure',
+  });
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /result/);
+});
+
+test('每个敏感字段出现在日志中时都明确失败', async () => {
+  for (const key of ['password', 'token', 'secret', 'authorization', 'databaseUrl', 'idCard', 'bankCard']) {
+    const result = await validate({
+      timestamp: '2026-07-09 08:00:00',
+      level: 'info',
+      service: 'backend',
+      instanceId: 'blue',
+      env: 'production',
+      message: 'request completed',
+      body: { [key]: 'not-allowed' },
+    });
+
+    assert.notEqual(result.status, 0, key);
+    assert.match(result.stderr, /Sensitive/, key);
+  }
+});
+
+test('HTTP 成功结果与截断数组可通过验证', async () => {
+  const result = await validate({
+    timestamp: '2026-07-09 08:00:00',
+    level: 'info',
+    service: 'backend',
+    instanceId: 'blue',
+    env: 'production',
+    message: 'request completed',
+    query: { page: '1' },
+    body: {
+      user: 'operator',
+      permissions: [...Array.from({ length: 500 }, (_, index) => index), '[TRUNCATED 1 ITEMS]'],
+    },
+    statusCode: 201,
+    result: 'success',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+});
+
+test('超过 500 项且没有截断标记时明确失败', async () => {
+  const result = await validate({
+    timestamp: '2026-07-09 08:00:00',
+    level: 'info',
+    service: 'backend',
+    instanceId: 'blue',
+    env: 'production',
+    message: 'request completed',
+    body: { items: Array.from({ length: 501 }, (_, index) => index) },
+  });
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /truncation/);
+});
+
+test('UTC ISO timestamp 时明确失败', async () => {
+  const result = await validate({
+    timestamp: '2026-07-09T00:00:00.000Z',
+    level: 'info',
+    service: 'backend',
+    instanceId: 'blue',
+    env: 'production',
+    message: 'request completed',
+  });
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /timestamp/);
+});

package/.well-known/skills/wdyy-logging-standard/templates/frontend-error-report.template.ts

@@ -0,0 +1,22 @@
+type FrontendErrorReport = {
+  message: string;
+  stack?: string;
+  path: string;
+  traceId?: string;
+  occurredAt: string;
+};
+
+export async function reportFrontendError(report: FrontendErrorReport): Promise<void> {
+  const payload = {
+    ...report,
+    message: report.message.slice(0, 500),
+    stack: report.stack?.slice(0, 2000),
+  };
+  const response = await fetch('/api/client-errors', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    credentials: 'same-origin',
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) throw new Error(`Frontend error report failed: ${response.status}`);
+}

package/.well-known/skills/wdyy-logging-standard/templates/logger.template.ts

@@ -0,0 +1,74 @@
+export type LogContext = {
+  traceId?: string;
+  userId?: string;
+  method?: string;
+  path?: string;
+  statusCode?: number;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  durationMs?: number;
+  errorCode?: string;
+  params?: Record<string, unknown>;
+};
+
+export type LogEntry = LogContext & {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error';
+  service: string;
+  instanceId: string;
+  env: string;
+  message: string;
+  result?: 'success' | 'failure';
+};
+
+const sensitiveKeys = new Set([
+  'password', 'token', 'secret', 'authorization', 'databaseurl', 'idcard', 'bankcard',
+]);
+
+export const redact = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    const items = value.slice(0, 500).map(redact);
+    return value.length > 500
+      ? [...items, '[TRUNCATED ' + (value.length - 500) + ' ITEMS]']
+      : items;
+  }
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => (
+    sensitiveKeys.has(key.toLowerCase()) ? [] : [[key, redact(item)]]
+  )));
+};
+
+const pad = (value: number) => String(value).padStart(2, '0');
+
+export const formatLocalTimestamp = (date = new Date()): string => (
+  [date.getFullYear(), pad(date.getMonth() + 1), pad(date.getDate())].join('-')
+  + ' '
+  + [pad(date.getHours()), pad(date.getMinutes()), pad(date.getSeconds())].join(':')
+);
+
+export const createLogFileName = (date = new Date()): string => (
+  formatLocalTimestamp(date).replace(' ', '_').replaceAll(':', '-') + '.log'
+);
+
+const resultForStatusCode = (statusCode: number): LogEntry['result'] => {
+  if (statusCode >= 100 && statusCode <= 399) return 'success';
+  if (statusCode >= 400 && statusCode <= 599) return 'failure';
+  return undefined;
+};
+
+export const toLogEntry = (level: LogEntry['level'], message: string, context: LogContext): LogEntry => {
+  const sanitizedContext = redact(context) as LogContext;
+  const result = sanitizedContext.statusCode === undefined
+    ? undefined
+    : resultForStatusCode(sanitizedContext.statusCode);
+  return {
+    timestamp: formatLocalTimestamp(),
+    level,
+    service: process.env.SERVICE_NAME ?? 'backend',
+    instanceId: process.env.INSTANCE_ID ?? 'local',
+    env: process.env.NODE_ENV ?? 'development',
+    message,
+    ...sanitizedContext,
+    ...(result ? { result } : {}),
+  };
+};

package/README.md

@@ -0,0 +1,65 @@
+# wdyy_skills
+
+面向企业内部软件开发的精简 Agent Skill 仓库。开发流程采用 [OpenSpec](https://github.com/Fission-AI/OpenSpec)；本仓库只保留技术栈以外、需要独立专业约束与可执行验证的企业规则。
+
+## 体系结构
+
+```text
+AGENTS.md                         全局基线、技术栈、OpenSpec 流程与 Skill 路由
+OpenSpec                           单项变更的需求、设计、任务、实施与归档
+.well-known/skills/wdyy-*         数据库、内部接口、日志、部署的专业规则
+```
+
+当前 `.well-known/skills/index.json` 登记 4 个企业 Skill。
+
+| Skill | 职责 |
+|---|---|
+| `wdyy-database-standard` | PostgreSQL 18 数据库设计、版本化迁移、数据兼容性与 DDL 校验。 |
+| `wdyy-internal-api-standard` | 内部 REST 调用的认证、traceId、超时、受控重试、错误映射与响应校验。 |
+| `wdyy-logging-standard` | 结构化日志、敏感字段移除、traceId、前端异常上报与日志轮转。 |
+| `wdyy-deployment-standard` | 人工 SCP 交付、版本化前端资源、Docker 蓝绿发布与回滚。 |
+
+## 使用方式
+
+安装全局包后，在目标项目根目录执行：
+
+```bash
+npm install -g @wdyy/skills
+wdyy init
+```
+
+`wdyy init` 自动执行 `openspec init`，将 4 个受管理 Skill 安装到 `.agents/skills/`。若目标项目已有 `AGENTS.md`，原文件保持不变，命令将生成 `AGENTS_new.md`；每次运行都会覆盖更新 `.agents/skills/wdyy-*`，但不修改同级自定义 Skill。
+
+中大型变更先使用 `/opsx:explore` 或 `/opsx:propose <change-name>`，在方案确认后使用 `/opsx:apply`；完成验证后使用 `/opsx:archive`。涉及数据库、内部 API、日志、部署时，按 `AGENTS.md` 的路由加载相应企业 Skill。配置仅从环境变量读取，不得提交秘密或生产环境 `.env`。
+
+## 固定技术栈
+
+- Node.js 24、pnpm workspace、TypeScript
+- Vue 3、Vite、Pinia、Vue Router、Element Plus
+- NestJS、PostgreSQL 18
+- Redis、RabbitMQ 仅在工程师明确确认后启用
+
+## 仓库维护
+
+- 所有 Skill 位于 `.well-known/skills`。
+- 新增、更新、删除 Skill 后必须同步更新 `.well-known/skills/index.json`。
+- 自定义企业 Skill 的目录名和 frontmatter `name` 必须以 `wdyy-` 开头且保持一致。
+- 只修改 `wdyy-*` Skill；详细且易变的规则应放在对应的 `reference/`，可重复校验应放在 `scripts/`。
+
+## 名称迁移
+
+| 原名称 | 新名称 |
+|---|---|
+| `enterprise-database-standard` | `wdyy-database-standard` |
+| `enterprise-internal-api-standard` | `wdyy-internal-api-standard` |
+| `enterprise-logging-standard` | `wdyy-logging-standard` |
+| `enterprise-deployment-standard` | `wdyy-deployment-standard` |
+
+旧名称不再作为本仓库提供的 Skill 身份。请将项目规则与手动调用更新为相应的 `wdyy-*` 名称。
+
+## 验证
+
+```bash
+node --input-type=module -e "import fs from 'node:fs'; const x = JSON.parse(fs.readFileSync('.well-known/skills/index.json', 'utf8')); for (const s of x.skills) for (const f of s.files) fs.accessSync('.well-known/skills/' + s.name + '/' + f)"
+node --test $(find .well-known/skills -path '*/scripts/*.test.mjs' -print)
+```

package/bin/wdyy.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { run } from '../lib/wdyy-cli.js';
+
+const exitCode = await run(process.argv.slice(2));
+process.exitCode = exitCode;

package/lib/wdyy-cli.js

@@ -0,0 +1,124 @@
+import { spawnSync } from 'node:child_process';
+import { access, cp, mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const managedSkillNames = [
+  'wdyy-database-standard',
+  'wdyy-internal-api-standard',
+  'wdyy-logging-standard',
+  'wdyy-deployment-standard'
+];
+
+const generatedAgentsContent = `# 企业开发规则
+
+本项目使用 wdyy 企业 Skill。新增、更新、删除受管理 Skill 后，必须同步核对项目内 Skill 清单；Skill 目录名必须与 \`SKILL.md\` frontmatter 的 \`name\` 一致。
+
+## 固定技术栈
+
+- Node.js 24、pnpm workspace、TypeScript。
+- 前端：Vue 3、Vite、Pinia、Vue Router、Element Plus。
+- 后端：NestJS。
+- 数据库：PostgreSQL 18。
+- Redis、RabbitMQ 仅在工程师明确确认后引入。
+
+默认项目目录为 \`apps/frontend\`、\`apps/backend\`、\`packages\`、\`database/migrations\`、\`deploy/docker\`、\`deploy/nginx\`、\`docs\`、\`scripts\`、\`tests\`。配置仅从环境变量读取；不得提交秘密或生产环境 \`.env\`。
+
+## OpenSpec 工作流
+
+功能新增、跨模块变更、数据模型变更、重构和生产发布必须使用 OpenSpec：不明确时先执行 \`explore\`；明确需求时执行 \`propose <change-name>\`；涉及业务、接口、数据库、部署或不可逆决定时，必须等待工程师确认方案后执行 \`apply\`；完成实现与验证后执行 \`/opsx:archive\`。
+
+## Skill 路由
+
+| 场景 | 必须使用的 Skill |
+|---|---|
+| PostgreSQL 表、DDL、迁移、数据兼容性 | \`wdyy-database-standard\` |
+| 服务间 REST 调用、认证、超时、重试、错误映射 | \`wdyy-internal-api-standard\` |
+| 结构化日志、traceId、脱敏、前端异常上报 | \`wdyy-logging-standard\` |
+| Linux 发布、Docker 蓝绿、Nginx 切流、回滚 | \`wdyy-deployment-standard\` |
+
+## 通用边界
+
+- 项目根目录应提供真实可执行的 \`pnpm dev\`、\`pnpm build\`、\`pnpm test\`、\`pnpm lint\` 命令；\`pnpm dev\` 不得启动或管理数据库、缓存或消息队列。
+- 代码、配置、迁移、测试与部署文件必须以实际实现为准；不得用模板虚构已实现能力。
+- 任何破坏性数据库操作、生产发布、引入基础设施或新外部依赖，必须在 OpenSpec 方案中说明影响并获得工程师确认。
+- 不得静默吞错、跳过验证、以兜底逻辑掩盖未决问题。
+`;
+
+function printHelp() {
+  console.log('用法: wdyy init');
+  console.log('在当前项目生成 AGENTS 规则、安装 wdyy Skill，并执行 openspec init。');
+}
+
+async function installManagedSkills(targetRoot, writtenPaths) {
+  const skillsRoot = join(targetRoot, '.agents', 'skills');
+  await mkdir(skillsRoot, { recursive: true });
+  const temporaryRoot = await mkdtemp(join(skillsRoot, '.wdyy-skills-'));
+
+  try {
+    for (const skillName of managedSkillNames) {
+      const source = join(packageRoot, '.well-known', 'skills', skillName);
+      const prepared = join(temporaryRoot, skillName);
+      await cp(source, prepared, { recursive: true, force: true, errorOnExist: false });
+    }
+
+    for (const skillName of managedSkillNames) {
+      const destination = join(skillsRoot, skillName);
+      await rm(destination, { recursive: true, force: true });
+      await rename(join(temporaryRoot, skillName), destination);
+      writtenPaths.push(destination);
+      console.log(`已更新 Skill: ${destination}`);
+    }
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeAgentsFile(targetRoot, writtenPaths) {
+  const agentsPath = join(targetRoot, 'AGENTS.md');
+  let destination = agentsPath;
+  try {
+    await access(agentsPath);
+    destination = join(targetRoot, 'AGENTS_new.md');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  await writeFile(destination, generatedAgentsContent, 'utf8');
+  writtenPaths.push(destination);
+  console.log(`已写入项目规则: ${destination}`);
+}
+
+function initializeOpenSpec(targetRoot, writtenPaths) {
+  const result = spawnSync('openspec', ['init'], { cwd: targetRoot, stdio: 'inherit' });
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message ?? `退出码 ${result.status ?? 1}`;
+    console.error(`OpenSpec 初始化失败: ${detail}`);
+    console.error(`已写入路径:\n${writtenPaths.map((path) => `- ${path}`).join('\n')}`);
+    return result.status ?? 1;
+  }
+
+  console.log('OpenSpec 初始化完成。');
+  return 0;
+}
+
+export async function run(argumentsList) {
+  if (argumentsList.length === 1 && argumentsList[0] === 'init') {
+    const writtenPaths = [];
+    try {
+      await writeAgentsFile(process.cwd(), writtenPaths);
+      await installManagedSkills(process.cwd(), writtenPaths);
+      const openSpecExitCode = initializeOpenSpec(process.cwd(), writtenPaths);
+      if (openSpecExitCode !== 0) return openSpecExitCode;
+      console.log('wdyy 初始化完成。');
+      return 0;
+    } catch (error) {
+      console.error(`wdyy 初始化失败: ${error.message}`);
+      if (writtenPaths.length > 0) console.error(`已写入路径:\n${writtenPaths.map((path) => `- ${path}`).join('\n')}`);
+      return 1;
+    }
+  }
+
+  printHelp();
+  return argumentsList.length === 1 && ['--help', '-h'].includes(argumentsList[0]) ? 0 : 1;
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@wdyy/skills",
+  "version": "0.1.0",
+  "description": "企业内部开发 Skill 与项目初始化命令",
+  "type": "module",
+  "bin": {
+    "wdyy": "bin/wdyy.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    ".well-known/skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "lint": "node --check bin/wdyy.js && node --check lib/*.js",
+    "build": "node --check bin/wdyy.js && node --check lib/*.js",
+    "dev": "node bin/wdyy.js --help"
+  }
+}