wucaishi-generative-react-skill 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# wucaishi-generative-react-skill
+
+Codex skill for Wucaishi component package workflow, HTML-to-React component generation, build version confirmation, and Aliyun OSS upload.
+
+## Install
+
+Run with npx:
+
+```bash
+npx wucaishi-generative-react-skill@latest
+```
+
+The installer copies this skill into:
+
+```text
+~/.codex/skills/component-package-workflow-zh
+```
+
+If `CODEX_HOME` is set, it installs into:
+
+```text
+$CODEX_HOME/skills/component-package-workflow-zh
+```
+
+## Included Skills
+
+- `component-package-workflow-zh`
+- `react-component-spec-zh`
+- `html-template-to-react-components-zh`
+- `build-version-confirm-zh`
+- `upload-aliyun-oss-zh`
+
+## Installer Options
+
+```bash
+npx wucaishi-generative-react-skill@latest -- --help
+npx wucaishi-generative-react-skill@latest -- --target /path/to/skills/component-package-workflow-zh
+npx wucaishi-generative-react-skill@latest -- --no-backup
+```
+
+By default, if a target skill already exists, the installer creates a timestamped backup next to it before replacing it.
+
+## Publish
+
+```bash
+npm login
+npm pack --dry-run
+npm publish
+```
+
+Before publishing, inspect the package contents and make sure no local credentials, tokens, or machine-specific files are included.

package/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: component-package-workflow-zh
+description: 当任务涉及新建组件包、修改组件包、打包组件包、上传组件包、发布组件包、打包发布、上传发布、同步组件汇总文档或上传总文档时使用。输出和说明使用中文。
+---
+
+# 组件包流程 Skill
+
+这个 Skill 定义的是组件包开发与发布流程，不是通用仓库协作说明。
+
+只要任务涉及以下任一情形，就应优先使用本 Skill：
+
+- 新建组件包
+- 修改组件包
+- 打包组件包
+- 上传组件包
+- 发布组件包
+- 打包发布
+- 上传发布
+- 同步组件汇总文档
+- 上传组件汇总文档
+
+## 使用方式
+
+处理组件包任务时，默认按下面顺序推进，不要跳步：
+
+1. 生成组件包模板
+2. 自定义开发组件包
+3. 发布组件包
+
+如果任务只是其中某一段，也应先检查前置阶段是否已经满足，再继续后续动作。
+
+## 子 Skill 路由
+
+本 Skill 是父 Skill。命中后按任务内容继续加载对应子 Skill：
+
+- 当任务涉及生成、编写、修改、编辑或重构 React 组件时，继续读取 `subskills/react-component-spec-zh/SKILL.md`
+- 当任务涉及从移动端 HTML 预览、HTML 模板、模板说明 Markdown、场景模块表格中抽取独立 React 组件时，继续读取 `subskills/html-template-to-react-components-zh/SKILL.md`，并先按该子 Skill 确认 HTML 文件和 Markdown 文件，不要自行猜测输入文件
+- 当任务涉及 `build`、打包、生成发布产物、准备发布、发布线上、打包发布、发布，或任何会产出可交付构建结果的命令时，继续读取 `subskills/build-version-confirm-zh/SKILL.md`
+- 当任务涉及发布组件包、打包发布、上传发布、上传组件包、上传 `dist/index.js`、同步组件包构建产物到 OSS，或校验组件包线上地址时，继续读取 `subskills/upload-aliyun-oss-zh/SKILL.md`
+
+如果一个任务同时涉及组件开发、打包和上传发布，这些子 Skill 都要读取，并且执行顺序应服从本 Skill 的主流程。
+
+## 第一阶段：生成组件包模板
+
+当用户要求开发一个新组件包时，先生成组件包模板，再进入自定义开发。
+
+### 组件包名称确认
+
+当用户要求新建或开发一个新组件包，但没有明确给出组件包名称时，不要自行推断或直接执行模板生成命令。应先用中文反问用户，请用户提供组件包名称，确认后再继续后续流程。
+
+推荐提问方式：
+
+- 请先告诉我本次要创建的组件包名称，发布到平台的组件名必须使用 `<中文场景或模板>_<中文组件名>_<english_component_code>`，例如 `会议总结_一句话看懂_meeting_minutes_summary`。其中 `english_component_code` 用于组件目录、`package.json.name` 和 OSS 路径。
+
+### 平台组件命名规则
+
+发布到平台、组件名称存在性校验接口、`src/manifest.json` 的 `name` 字段，统一使用下面格式：
+
+```text
+<中文场景或模板>_<中文组件名>_<english_component_code>
+```
+
+示例：
+
+```text
+会议总结_一句话看懂_meeting_minutes_summary
+```
+
+要求：
+
+- `<中文场景或模板>` 使用模板或业务场景中文名称。
+- `<中文组件名>` 使用组件中文展示名称。
+- `<english_component_code>` 使用小写英文、数字和下划线，表达组件机器语义，例如 `meeting_minutes_summary`。
+- 创建本地目录、执行 `npx create-wucaishi-cpn@latest`、填写 `package.json.name` 和生成 OSS prefix 时，默认使用 `english_component_code` 转成 kebab-case，例如 `meeting-minutes-summary`。
+- `src/manifest.json.name` 必须保留完整平台组件名，例如 `会议总结_一句话看懂_meeting_minutes_summary`，不能只写英文 code。
+- 如果用户只提供中文名称或只提供英文 code，必须先追问补齐完整格式，不要自行编造缺失部分。
+
+### 组件名称存在性校验
+
+创建组件模板前，必须先调用名称存在性校验接口，不能跳过。
+
+固定接口：
+
+- 登录接口：`POST https://prism-stone-pre.byering.com/api/web/auth/login`
+- 登录账号：由用户提供，不能使用默认账号
+- 登录密码：由用户提供，不能使用默认密码
+- 校验接口：`POST https://prism-stone-pre.byering.com/api/admin/deliverable-h5-components/exists`
+- 校验入参：`{"name":"组件包名称"}`
+- 返回语义：`entity.exists` 表示组件名称是否已经存在。
+
+执行规则：
+
+- 当用户给出组件名称后，先读取本地已保存的登录账号和密码；如果本地没有，再提示用户输入登录账号和密码。
+- 用户提供账号密码后，先登录获取 Bearer Token；登录成功后把账号和密码保存到本地，供后续相关操作直接使用。
+- 本地凭据保存路径固定为 `~/.wucaishi-component-workflow/auth.json`，文件权限应限制为 `600`。
+- 不要在 skill、脚本或命令示例中写入默认账号、默认密码或个人凭据。
+- 如果接口返回 `entity.exists === true`，表示组件名称已存在，必须停止创建并提示：`组件名称已存在，请更换组件名称`。
+- 如果接口返回 `entity.exists === false`，表示组件名称可用，继续执行模板创建。
+- 如果接口失败或返回结构异常，先说明接口错误，不要继续创建模板。
+
+推荐命令：
+
+```bash
+node .agents/skills/component-package-workflow-zh/scripts/check_component_name_exists.mjs \
+  --name 组件包名 \
+  --phone 登录账号 \
+  --password 登录密码
+```
+
+如果本地已经保存过账号密码，后续可直接执行：
+
+```bash
+node .agents/skills/component-package-workflow-zh/scripts/check_component_name_exists.mjs \
+  --name 组件包名
+```
+
+### 模板创建规则
+
+直接在当前仓库目录执行以下命令生成组件包基础模板：
+
+```bash
+npx create-wucaishi-cpn@latest 组件包名
+```
+
+要求：
+
+- `组件包名` 使用有明确语义的名字
+- 如果用户没有输入组件包名称，必须先反问用户，不要擅自命名
+- 创建模板前必须先完成组件名称存在性校验，确认 `entity.exists === false`
+- 执行名称校验前，如果本地没有已保存凭据，且用户没有提供登录账号和密码，必须先向用户索要，不要使用默认凭据
+- 不要跳过模板创建步骤直接手写整套组件包
+- 如果模板已经生成，优先在模板基础上修改
+
+## 第二阶段：自定义开发组件包
+
+在模板基础上继续开发组件包，包括但不限于：
+
+- 调整组件结构
+- 定义或修改 Props
+- 编写样式和交互逻辑
+- 按 H5 移动端设计稿、截图参考或用户给出的视觉素材提取组件结构与数据边界
+- 生成或修改组件后，启动本地预览并打开预览页面进行查看与确认
+- 完成预览后，明确把本地预览地址反馈给用户
+- 补齐导出内容
+- 补齐组件包文档
+
+### 开发要求
+
+- 优先保留模板目录结构，不要无故推倒重建
+- 组件包是可复用交付物，不要按一次性页面片段的方式编写
+- 当组件面向 H5 或基于截图生成时，必须继续遵循 React 子 Skill 中的移动端适配、375 设计稿基准和截图解析规则
+- 如果组件对外提供使用说明，组件文档统一维护在 `README.md`
+- 页面生成或完成修改后，应主动启动本地预览，打开预览页面检查实际效果，并把本地预览地址明确告知用户，再继续后续流程
+- 开发完成并完成必要自检后再进入打包，不要边写边发布
+
+## 第三阶段：发布组件包
+
+当用户要求打包组件包、上传组件包、发布、发布组建、打包发布、同步更新总文档或上传总文档时，统一按本阶段内的各子阶段顺序推进，不要跳步执行。
+
+### 阶段一：打包组件包
+
+当用户要求打包组件包时，按以下顺序执行：
+
+1. 确认组件包开发已经完成
+2. 确认必要文档已经同步，并完成必要自检
+3. 先继续读取 `subskills/build-version-confirm-zh/SKILL.md`，并让用户确认本次要如何更新版本号
+4. 完成版本同步后，执行打包命令
+5. 打包成功后再进入上传流程
+
+当前仓库可用的打包命令为：
+
+```bash
+npm run build
+```
+
+打包约束：
+
+- 打包失败时先修复问题，再重新打包
+- 没有完成开发或自检时，不要直接打包交付
+- 只要进入打包流程，就应继续读取 `subskills/build-version-confirm-zh/SKILL.md`，先完成版本确认和版本更新，再执行构建
+
+### 阶段二：上传组件包
+
+当用户要求上传组件包时，上传流程统一通过 `subskills/upload-aliyun-oss-zh/SKILL.md` 执行，不再在父 Skill 内重复维护另一套上传步骤。
+
+上传约束：
+
+- 不要在上传目标不明确时擅自发布
+- 不要跳过打包直接上传
+- 进入组件包上传流程时，必须继续读取 `subskills/upload-aliyun-oss-zh/SKILL.md`，并完全按该子 Skill 的规则执行
+- 如果上传规则需要调整，应优先修改子 Skill，而不是在父 Skill 里追加平行规则
+
+## 当前已知命令
+
+- 组件包生成命令：`npx create-wucaishi-cpn@latest 组件包名`
+- 当前打包命令：`npm run build`

package/bin/install.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, rm, rename, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const SKILL_NAME = "component-package-workflow-zh";
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function printHelp() {
+  console.log(`usage: wucaishi-generative-react-skill [options]
+
+Install the component-package-workflow-zh Codex skill.
+
+options:
+  -h, --help              Show help
+  --target PATH           Install to a custom skill directory
+  --no-backup             Replace an existing target without creating a backup
+
+environment:
+  CODEX_HOME              Defaults to ~/.codex when not set`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    target: null,
+    backup: true,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const nextValue = () => {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error(`${arg} requires a value`);
+      }
+      i += 1;
+      return value;
+    };
+
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    } else if (arg === "--target") {
+      args.target = nextValue();
+    } else if (arg === "--no-backup") {
+      args.backup = false;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return args;
+}
+
+async function pathExists(pathValue) {
+  try {
+    await stat(pathValue);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultTarget() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "skills", SKILL_NAME);
+}
+
+function timestamp() {
+  return new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..+$/, "")
+    .replace("T", "-");
+}
+
+async function copySkill(target) {
+  await mkdir(dirname(target), { recursive: true });
+  await mkdir(target, { recursive: true });
+
+  for (const entry of ["SKILL.md", "scripts", "subskills"]) {
+    await cp(join(PACKAGE_ROOT, entry), join(target, entry), {
+      recursive: true,
+      force: true,
+    });
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const target = resolve(args.target || defaultTarget());
+
+  if (await pathExists(target)) {
+    if (args.backup) {
+      const backupTarget = `${target}.backup-${timestamp()}`;
+      await rename(target, backupTarget);
+      console.log(`已备份已有 skill：${backupTarget}`);
+    } else {
+      await rm(target, { recursive: true, force: true });
+    }
+  }
+
+  await copySkill(target);
+
+  console.log(`已安装 ${SKILL_NAME} 到：${target}`);
+  console.log("请重启 Codex 或刷新 skills 后使用。");
+}
+
+main().catch((error) => {
+  console.error(`安装失败：${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "wucaishi-generative-react-skill",
+  "version": "0.1.0",
+  "description": "Codex skill for Wucaishi component package workflow and HTML-to-React generation.",
+  "type": "module",
+  "bin": {
+    "wucaishi-generative-react-skill": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "SKILL.md",
+    "scripts",
+    "subskills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "codex-skill",
+    "react",
+    "html-to-react",
+    "component-workflow",
+    "wucaishi"
+  ],
+  "license": "UNLICENSED"
+}

package/scripts/check_component_name_exists.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const API_BASE = 'https://prism-stone-pre.byering.com/api';
+const AUTH_CACHE_PATH = join(homedir(), '.wucaishi-component-workflow', 'auth.json');
+
+function fail(message, code = 1) {
+	console.error(`错误：${message}`);
+	process.exit(code);
+}
+
+function parseArgs(argv) {
+	const args = {
+		name: null,
+		phone: null,
+		password: null,
+	};
+
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const nextValue = () => {
+			const value = argv[i + 1];
+			if (!value || value.startsWith('--')) {
+				fail(`${arg} 缺少参数值`);
+			}
+			i += 1;
+			return value;
+		};
+
+		if (arg === '-h' || arg === '--help') {
+			printHelp();
+			process.exit(0);
+		} else if (arg === '--name') {
+			args.name = nextValue();
+		} else if (arg === '--phone') {
+			args.phone = nextValue();
+		} else if (arg === '--password') {
+			args.password = nextValue();
+		} else {
+			fail(`未知参数：${arg}`);
+		}
+	}
+
+	if (!args.name || !args.name.trim()) {
+		fail('必须传入 --name 组件名');
+	}
+
+	args.name = args.name.trim();
+	args.phone = args.phone ? args.phone.trim() : null;
+	args.password = args.password ? args.password.trim() : null;
+	return args;
+}
+
+function printHelp() {
+	console.log(`usage: check_component_name_exists.mjs --name COMPONENT_NAME [options]
+
+创建组件模板前校验组件名称是否已存在。
+
+options:
+  -h, --help                    显示帮助
+  --name COMPONENT_NAME          组件名，必填
+  --phone PHONE                 登录账号，首次登录必填；之后可读取本地缓存
+  --password PASSWORD           登录密码，首次登录必填；之后可读取本地缓存`);
+}
+
+async function loadSavedCredentials() {
+	try {
+		const raw = await readFile(AUTH_CACHE_PATH, 'utf8');
+		const saved = JSON.parse(raw);
+		if (saved && typeof saved.phone === 'string' && typeof saved.password === 'string') {
+			return {
+				phone: saved.phone.trim(),
+				password: saved.password.trim(),
+			};
+		}
+	} catch {
+		return null;
+	}
+	return null;
+}
+
+async function saveCredentials(phone, password) {
+	const payload = JSON.stringify({ phone, password }, null, 2);
+	await mkdir(dirname(AUTH_CACHE_PATH), { recursive: true, mode: 0o700 });
+	await writeFile(AUTH_CACHE_PATH, payload, { mode: 0o600 });
+	await chmod(AUTH_CACHE_PATH, 0o600);
+}
+
+async function resolveCredentials(args) {
+	const saved = await loadSavedCredentials();
+	const phone = args.phone || saved?.phone;
+	const password = args.password || saved?.password;
+
+	if (!phone || !password) {
+		fail(`缺少登录账号或密码。请先传入 --phone 登录账号 --password 登录密码，登录成功后会保存到本地：${AUTH_CACHE_PATH}`);
+	}
+
+	return { phone, password };
+}
+
+async function requestJson(method, url, { body, token } = {}) {
+	const headers = { Accept: 'application/json' };
+	const init = { method, headers };
+	if (body !== undefined) {
+		headers['Content-Type'] = 'application/json';
+		init.body = JSON.stringify(body);
+	}
+	if (token) {
+		headers.Authorization = `Bearer ${token}`;
+	}
+
+	let response;
+	try {
+		response = await fetch(url, init);
+	} catch (error) {
+		fail(`请求失败：${method} ${url}\n${error.message}`);
+	}
+
+	const raw = await response.text();
+	if (!response.ok) {
+		fail(`HTTP ${response.status}：${method} ${url}\n${raw}`);
+	}
+
+	try {
+		return JSON.parse(raw);
+	} catch {
+		fail(`接口返回不是 JSON：${method} ${url}\n${raw}`);
+	}
+}
+
+function entityOrFail(payload, apiName) {
+	if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+		fail(`${apiName} 返回不是对象：${String(payload)}`);
+	}
+	if (String(payload.code) !== '10000') {
+		fail(`${apiName} 返回失败：${JSON.stringify(payload, null, 2)}`);
+	}
+	if (!payload.entity || typeof payload.entity !== 'object' || Array.isArray(payload.entity)) {
+		fail(`${apiName} 返回缺少 entity：${JSON.stringify(payload, null, 2)}`);
+	}
+	return payload.entity;
+}
+
+async function login(phone, password) {
+	const body = { phone, password };
+	const payload = await requestJson('POST', `${API_BASE}/web/auth/login`, { body });
+	const entity = entityOrFail(payload, '测试登录');
+	if (!entity.accessToken) {
+		fail(`测试登录返回缺少 entity.accessToken：${JSON.stringify(payload, null, 2)}`);
+	}
+	return entity.accessToken;
+}
+
+async function checkExists(token, name) {
+	const payload = await requestJson('POST', `${API_BASE}/admin/deliverable-h5-components/exists`, {
+		body: { name },
+		token,
+	});
+	const entity = entityOrFail(payload, '组件名称存在性校验');
+	if (typeof entity.exists !== 'boolean') {
+		fail(`组件名称存在性校验返回缺少 boolean entity.exists：${JSON.stringify(payload, null, 2)}`);
+	}
+	return entity.exists;
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const credentials = await resolveCredentials(args);
+	console.log(`API 域名：${API_BASE}`);
+	console.log(`登录账号：${credentials.phone}`);
+	console.log(`待校验组件名：${args.name}`);
+
+	const token = await login(credentials.phone, credentials.password);
+	await saveCredentials(credentials.phone, credentials.password);
+	const exists = await checkExists(token, args.name);
+
+	if (exists) {
+		fail(`组件名称已存在，请更换组件名称：${args.name}`, 2);
+	}
+
+	console.log(`组件名称可用：${args.name}`);
+}
+
+main().catch((error) => fail(error.stack || error.message || String(error)));

package/scripts/check_h5_font_sizes.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const root = process.argv[2] || "src";
+const MAX_FONT_PX = 24;
+const allowLargeFontMarker = "allow-large-font";
+
+function walk(dir) {
+  const entries = readdirSync(dir);
+  return entries.flatMap((entry) => {
+    const path = join(dir, entry);
+    const stat = statSync(path);
+    if (stat.isDirectory()) {
+      return walk(path);
+    }
+    return /\.(styles\.ts|styles\.tsx|tsx|ts)$/.test(entry) ? [path] : [];
+  });
+}
+
+function collectNumbers(pattern, text) {
+  return Array.from(text.matchAll(pattern), (match) => Number.parseFloat(match[1])).filter(Number.isFinite);
+}
+
+function isFontSizeLine(line) {
+  return /font-size\s*:/.test(line);
+}
+
+const findings = [];
+
+for (const file of walk(root)) {
+  const source = readFileSync(file, "utf8");
+  const lines = source.split(/\r?\n/);
+
+  lines.forEach((line, index) => {
+    if (!isFontSizeLine(line) || line.includes(allowLargeFontMarker)) {
+      return;
+    }
+
+    const trimmed = line.trim();
+    const largePx = collectNumbers(/(\d+(?:\.\d+)?)px\b/g, line).filter((value) => value > MAX_FONT_PX);
+    const largeVwFn = collectNumbers(/\bvw\(\s*(\d+(?:\.\d+)?)\s*\)/g, line).filter((value) => value > MAX_FONT_PX);
+    const hasBareVwFunction = /\bvw\(\s*\d+(?:\.\d+)?\s*\)/.test(line) && !/\bfluidFont\(/.test(line) && !/\bclamp\(/.test(line);
+    const hasBareVwUnit = /\d+(?:\.\d+)?vw\b/.test(line) && !/\bclamp\(/.test(line);
+
+    if (largePx.length > 0) {
+      findings.push({
+        file,
+        line: index + 1,
+        reason: `font-size 超过 ${MAX_FONT_PX}px：${largePx.join(", ")}`,
+        text: trimmed,
+      });
+    }
+
+    if (largeVwFn.length > 0) {
+      findings.push({
+        file,
+        line: index + 1,
+        reason: `font-size 的 vw() 输入超过 ${MAX_FONT_PX}px：${largeVwFn.join(", ")}`,
+        text: trimmed,
+      });
+    }
+
+    if (hasBareVwFunction || hasBareVwUnit) {
+      findings.push({
+        file,
+        line: index + 1,
+        reason: "font-size 不应裸用无边界 vw，改用 fluidFont() 或 clamp()",
+        text: trimmed,
+      });
+    }
+  });
+}
+
+if (findings.length > 0) {
+  console.error("H5 font size check failed:");
+  for (const finding of findings) {
+    console.error(`${relative(process.cwd(), finding.file)}:${finding.line} ${finding.reason}`);
+    console.error(`  ${finding.text}`);
+  }
+  process.exit(1);
+}
+
+console.log("H5 font size check passed.");