yq-frontend-skills 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# yq-frontend-skills
+
+`yq-frontend-skills` 是一套面向前端开发团队的**全局跨智能体开发技能（Skills）与工作流（Workflows）规范管理框架**。
+
+它旨在解决团队在使用各大智能体开发工具（Cursor、Claude Code 等）时出现“盲目写代码 (Vibe Coding)”的问题，强制要求在开发前进行头脑风暴与方案设计评审。通过**全局用户级分发**机制，做到前端项目目录 **零文件污染**、**零 Git 提交**，且**一处更新，所有开发环境同步生效**。
+
+---
+
+## 🌟 核心特性
+
+* 🚀 **全局原生免污染**：技能文件物理分发到开发者的系统 Home 用户目录下，无需在前端业务项目中物理拷贝文件或建立软链，保障 Git 代码仓库 100% 纯净。
+* 🔄 **跨智能体对齐**：统一适配 Cursor、Claude Code、Codex 的全局 `SKILL.md` 标准，以及 Gemini/Antigravity 的全局 `Workflow` 标准与 OpenCode 的全局 `AGENTS.md` 规范。
+* 🛑 **门控状态机流控制 (Checkpoints)**：内置 `yq-design-schema`（前端方案制定）和 `yq-refactor`（安全重构）核心任务流，用阶段门控（如未通过方案评审严禁调用编码工具）纠正 AI 编码习惯。
+
+---
+
+## 🛠️ 支持的智能体工具及全局路径
+
+| 智能体工具 | 全局加载路径 | 装载类型 |
+| :--- | :--- | :--- |
+| **Claude Code** | `~/.claude/skills/` | 原生全局 `SKILL.md` 个人技能 |
+| **Cursor** | `~/.cursor/skills/` | 原生全局 `SKILL.md` 个人技能 |
+| **Codex CLI / App** | `~/.codex/skills/` | 原生全局 `SKILL.md` 个人技能 |
+| **Gemini / Antigravity** | `~/.gemini/config/global_workflows/` | 全局 Markdown 任务工作流 |
+| **OpenCode** | `~/.config/opencode/` | 全局 `AGENTS.md` 前端宪法 |
+
+---
+
+## 💾 安装与使用
+
+### 1. 全局安装
+
+通过 NPM 全局安装该工具包：
+
+```bash
+npm install -g yq-frontend-skills
+```
+
+### 2. 全局智能体技能注册
+
+安装完成后，在终端的任何路径下执行以下命令。工具会自动识别您系统当前已配置的智能体，并将核心技能与工作流编译分发至对应的全局路径下：
+
+```bash
+yq-skills register
+```
+
+### 3. 一键同步与覆盖更新
+
+当 `yq-frontend-skills` 发布新版本更新了前端开发规范时，开发人员只需运行包更新，并执行一键同步覆盖，本地所有关联智能体的技能就会同步升级：
+
+```bash
+npm update -g yq-frontend-skills
+yq-skills sync
+```
+
+---
+
+## 🚀 内置核心工作流
+
+### 1. `/yq-design-schema` (前端方案制定)
+强制约束智能体在接到需求后，必须按以下步骤推进，不得擅自修改代码：
+1. **Phase 1: Brainstorming (头脑风暴)**：探索当前项目依赖与副作用，识别并提出未明确的疑问。
+2. **Phase 2: Planning (方案设计)**：编写并向用户汇报包含接口契约、组件拆分 (Mermaid 图) 及 TODO 任务列表的技术设计方案。
+3. **Phase 3: Review (方案评审 - 门控点)**：**强制禁止**调用任何代码修改工具，等待用户阅读并回复“批准”。
+4. **Phase 4: Implementation (执行实施)**：获得批准后，小步快跑地实施方案。
+5. **Phase 5: Verification (方案校验)**：执行构建、类型检查与单元测试，输出修改日志链接。
+
+### 2. `/yq-refactor` (安全重构)
+引导智能体安全、高内聚地优化现有代码：
+1. **Step 1: Bad Smell Identification**：定位长方法、超大组件等坏味道，梳理依赖。
+2. **Step 2: Extract & Abstract**：抽离逻辑 hooks 或是子 UI 原子组件，保证职责单一。
+3. **Step 3: Replace & Verify**：对原位置进行平滑替换，回归测试保证不改变原有外部功能行为。
+
+---
+
+## ❓ 常见问题 (FAQ)
+
+### Q: 运行了 `yq-skills register` 后，为什么智能体无法调出 `/yq-design-schema`？
+**A**: 智能体工具（包括 Antigravity IDE、Claude Code、Cursor 等）的全局技能和工作流是在**会话（Session）冷启动时一次性载入内存的**。已启动的终端或 IDE 会话无法实时刷新，请**关闭当前会话/终端窗口并重新打开一个新的会话**，即可成功加载并唤起新技能。
+
+### Q: 如果我想修改团队的方案评估清单（Checklist）该怎么办？
+**A**: 全局技能包内置了 `skills/workflows/design-schema/checklist.json` 规范清单，团队 Leader 可以将该项目 fork 后进行定制，然后发布到私有 NPM 源上供团队更新使用。

package/bin/yq-skills.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { registerSkills } from '../src/register.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// 读取版本号
+const pkgPath = path.join(__dirname, '..', 'package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+yq-frontend-skills v${pkg.version}
+前端智能体全局开发技能管理工具
+
+用法:
+  yq-skills <command>
+
+可用命令:
+  register     向系统已安装的智能体（Cursor, Claude, Codex, Gemini 等）注册全局前端方案技能
+  sync         同 register，重新读取核心规范并强制更新覆盖全局配置
+  --version, -v 打印版本号
+  --help, -h    打印此帮助信息
+  `);
+}
+
+switch (command) {
+  case 'register':
+  case 'sync':
+    registerSkills();
+    break;
+
+  case '--version':
+  case '-v':
+    console.log(`v${pkg.version}`);
+    break;
+
+  case '--help':
+  case '-h':
+  case undefined:
+    printHelp();
+    break;
+
+  default:
+    console.error(`未知命令: ${command}`);
+    printHelp();
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "yq-frontend-skills",
+  "version": "1.0.0",
+  "description": "A cross-agent global workflows and skills framework for frontend design schema.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "yq-skills": "bin/yq-skills.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 0"
+  },
+  "keywords": [
+    "cursor",
+    "claude",
+    "codex",
+    "gemini",
+    "opencode",
+    "skills",
+    "workflows",
+    "frontend"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/skills/domains/api/RULES.md

@@ -0,0 +1,7 @@
+# API 规范与对接指南 (api)
+
+本指南针对前端团队与后端的接口对接制定。主要规范包括：
+
+1. **接口契约定义**：任何 API 的引入均需写明接口 URL、入参类型、出参格式。
+2. **Mock 机制优先**：若后端接口尚未就绪，必须先在本地 `mock/` 目录配置契约数据，方便智能体和开发人员进行界面联调。
+3. **接口异常处理**：所有接口请求必须覆盖成功的处理以及失败的全局与局部友好报错。

package/skills/domains/component/RULES.md

@@ -0,0 +1,7 @@
+# 前端组件设计规范 (component)
+
+本指南规范前端 UI 与逻辑组件的抽离和划分：
+
+1. **高内聚低耦合**：组件应当根据单一职责原则（SRP）进行职责边界划分。
+2. **样式隔离**：所有的 CSS 必须采用 scoped/css-modules 进行模块样式隔离，严禁直接定义无范围的全局选择器导致样式污染。
+3. **Props 规范**：显式定义 `props` 的数据类型（Type）、默认值（Default）与必填状态（Required），利于类型检查与健壮度。

package/skills/domains/i18n/RULES.md

@@ -0,0 +1,6 @@
+# 国际化开发规范 (i18n)
+
+本指南指导前端开发进行词条国际化处理：
+
+1. **中文文案抽离**：新增代码中的任何汉字文案，**禁止**直接硬编码（Hard-coded）在 HTML/JS/VUE 视图中，必须使用 `$t()` 或对应的多语言加载函数进行包裹。
+2. **多语言 Key 规范**：使用模块化前缀命名多语言 Key，例如 `modular.feature.button_label`，禁止命名无意义的 Key 如 `text1`, `button2`。

package/skills/workflows/design-schema/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: yq-design-schema
+description: 协助前端团队在开发新功能、修改 API 或重构组件前，制定规范、清晰的技术方案，确保架构合理与协作通畅。
+globs:
+  - "**/*.js"
+  - "**/*.ts"
+  - "**/*.vue"
+  - "**/*.tsx"
+  - "**/*.jsx"
+---
+
+# 前端方案制定工作流 (yq-design-schema)
+
+本工作流旨在规范智能体（AI）的编码流程，防止未经理性设计而直接进入代码实现。在进行任何代码修改前，智能体**必须**遵循以下五个阶段：
+
+## 阶段流程与门控 (Gates & Checkpoints)
+
+### Phase 1: Brainstorming (需求探索与头脑风暴)
+当接收到用户的需求或 bug 修复任务时，不要立即进入代码修改。你应当：
+1. **分析现状**：理清当前涉及到的文件路径、已有逻辑以及技术依赖关系。
+2. **评估副作用**：评估此次修改是否会影响现有的组件、状态管理或公共 API。
+3. **识别疑问**：若需求描述不清或技术边界模糊，应当整理出疑问向用户确认。
+4. **验证门控**：完成此阶段后，方可启动 Phase 2。
+
+### Phase 2: Planning (技术方案设计)
+本阶段需要制定详细的实现方案，输出清晰的架构文档。方案必须包括：
+1. **数据模型与状态流**：新设计的数据结构和组件状态流向。
+2. **API 接口契约**：如涉及新旧接口对接，需写明入参、出参和 Mock 契约。
+3. **组件设计**：组件的拓扑结构与职责划分（建议使用 Mermaid 图表达）。
+4. **重构/修改步骤**：列出清晰的 TODO 计划列表。
+5. **门控说明**：方案制定后，**必须**输出一份清晰的技术方案文档并呈现给用户。
+
+### Phase 3: Review (方案评审)
+* **强制约束**：在此阶段，智能体**被禁止**调用任何代码编写或文件修改工具。
+* **门控条件**：必须等待用户阅读你的 Planning 方案。当且仅当用户回复“批准”或“确认”后，方可进入 Phase 4 实施阶段。
+
+### Phase 4: Implementation (执行实施)
+根据已经过评审的方案计划，开始编写代码。在这个过程中：
+1. 保持小步快跑，每个逻辑单元修改后应及时自我 review。
+2. 遇到未预料到的阻碍时，应立即停止，更新 Planning 方案并重新报审，不得擅自修改评审范围外的代码。
+
+### Phase 5: Verification (方案校验)
+开发完成后，必须进行质量校验：
+1. 运行项目内置的编译、类型检查或单元测试命令。
+2. 提供明确的修改日志（Walkthrough）并指出修改的核心文件链接，供用户做最终审查。

package/skills/workflows/design-schema/checklist.json

@@ -0,0 +1,29 @@
+{
+  "name": "frontend-design-checklist",
+  "version": "1.0.0",
+  "categories": [
+    {
+      "name": "Architecture & Clean Code",
+      "items": [
+        "是否遵循单一职责原则拆分组件？",
+        "是否对现有业务逻辑引入了副作用（Side-effects）？",
+        "组件或函数是否有不必要的耦合？"
+      ]
+    },
+    {
+      "name": "API & Data flow",
+      "items": [
+        "API 契约是否已与后端对齐，是否存在入参/出参模糊字段？",
+        "对于暂未上线的 API，是否定义了本地 Mock 数据？",
+        "状态管理流向是否单一，是否存在冗余数据源？"
+      ]
+    },
+    {
+      "name": "I18n & Assets",
+      "items": [
+        "所有新增和修改的文案，是否全部抽离到了多语言词条中？",
+        "是否使用了项目中已有的公共图标和静态资源？"
+      ]
+    }
+  ]
+}

package/skills/workflows/refactor/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: yq-refactor
+description: 协助前端团队进行模块重构、组件抽取、废弃代码清理，确保重构过程的安全与高内聚。
+globs:
+  - "**/*.js"
+  - "**/*.ts"
+  - "**/*.vue"
+  - "**/*.tsx"
+  - "**/*.jsx"
+---
+
+# 前端安全重构工作流 (yq-refactor)
+
+重构的目的是在**不改变软件外部行为**的前提下，提高代码的可读性、可维护性和复用性。本工作流定义了重构时的规范步骤：
+
+## 重构基本守则 (Refactoring Principles)
+
+1. **小步修改**：单次重构范围应控制在最小业务单元内，切忌把“重构”演变成“重写”。
+2. **测试守护**：在开始重构前，如果可能，请确保重构目标模块已覆盖了足够的单元测试或手工验证流程，重构后必须确保原有功能行为 100% 保持一致。
+3. **DRY 准则**：在抽离公共函数或组件时，遵循 Don't Repeat Yourself，优先复用，并进行合理的抽象。
+
+## 重构实施步骤 (Steps)
+
+### Step 1: Bad Smell Identification (识别重构目标)
+1. 找出长函数、上帝类、超大组件、重复文案或杂乱的状态流转。
+2. 梳理它的依赖链，做好备忘。
+
+### Step 2: Extract & Abstract (抽取与解耦)
+1. 将复杂的业务逻辑抽取为高内聚的 hooks 或纯函数。
+2. 将超大视图组件拆分为可复用的原子组件，通过 props 进行清晰的控制。
+
+### Step 3: Replace & Verify (替换与回归测试)
+1. 使用新抽离的组件/函数，在原位置做平滑替换。
+2. 运行构建脚本与类型检查，验证代码在浏览器中的表现，确保没有任何渲染或控制报错。

package/src/config.js

@@ -0,0 +1,26 @@
+import os from 'os';
+import path from 'path';
+
+/**
+ * 获取各大智能体在本地系统上的全局配置绝对路径
+ */
+export function getAgentPaths() {
+  const home = os.homedir();
+
+  return {
+    // Claude Code 全局技能目录
+    claude: path.join(home, '.claude', 'skills'),
+    
+    // Cursor 全局技能目录
+    cursor: path.join(home, '.cursor', 'skills'),
+    
+    // Codex 全局技能目录
+    codex: path.join(home, '.codex', 'skills'),
+    
+    // Gemini / Antigravity 全局 workflow 目录
+    gemini: path.join(home, '.gemini', 'config', 'global_workflows'),
+    
+    // OpenCode 全局规则目录
+    opencode: path.join(home, '.config', 'opencode')
+  };
+}

package/src/register.js

@@ -0,0 +1,148 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { getAgentPaths } from './config.js';
+import { formatSkill } from './templates/index.js';
+
+// 获取当前文件及项目的根目录（适用于 ES Module）
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.join(__dirname, '..');
+
+/**
+ * 极简的 YAML Frontmatter 解析器，避免引入外部依赖
+ * @param {string} content 原始 Markdown 文本
+ */
+function parseFrontmatter(content) {
+  const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+  const match = content.match(fmRegex);
+  
+  if (!match) {
+    return { frontmatter: {}, markdown: content };
+  }
+
+  const yamlStr = match[1];
+  const markdown = match[2];
+  const frontmatter = {};
+
+  const lines = yamlStr.split(/\r?\n/);
+  let currentKey = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.startsWith('-')) {
+      if (currentKey && Array.isArray(frontmatter[currentKey])) {
+        const val = trimmed.substring(1).trim().replace(/^["']|["']$/g, '');
+        frontmatter[currentKey].push(val);
+      }
+    } else {
+      const idx = trimmed.indexOf(':');
+      if (idx !== -1) {
+        const key = trimmed.substring(0, idx).trim();
+        const value = trimmed.substring(idx + 1).trim().replace(/^["']|["']$/g, '');
+        if (value === '') {
+          frontmatter[key] = [];
+          currentKey = key;
+        } else {
+          frontmatter[key] = value;
+          currentKey = null;
+        }
+      }
+    }
+  }
+
+  return { frontmatter, markdown };
+}
+
+/**
+ * 执行全局技能的注册与同步物理分发
+ */
+export function registerSkills() {
+  const agentPaths = getAgentPaths();
+  const skillsDir = path.join(projectRoot, 'skills', 'workflows');
+
+  console.log('\x1b[36m%s\x1b[0m', '>> 开始全局分发 yq-frontend-skills 前端方案制定技能...');
+
+  // 1. 读取并解析核心 Workflows 下的所有技能
+  if (!fs.existsSync(skillsDir)) {
+    console.error(`[Error] 找不到技能目录: ${skillsDir}`);
+    return false;
+  }
+
+  const skillDirs = fs.readdirSync(skillsDir).filter(name => {
+    return fs.statSync(path.join(skillsDir, name)).isDirectory();
+  });
+
+  const parsedSkills = [];
+
+  for (const skillName of skillDirs) {
+    const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) continue;
+
+    const rawContent = fs.readFileSync(skillPath, 'utf-8');
+    const { frontmatter, markdown } = parseFrontmatter(rawContent);
+    
+    parsedSkills.push({
+      dirName: skillName,
+      frontmatter,
+      markdown
+    });
+  }
+
+  // 2. 分发至各智能体的全局目录
+  // 适配 Cursor, Claude Code, Codex (它们使用统一的子目录 + SKILL.md 格式)
+  const fileBasedAgents = ['cursor', 'claude', 'codex'];
+  for (const agent of fileBasedAgents) {
+    const destDir = agentPaths[agent];
+    try {
+      for (const skill of parsedSkills) {
+        const targetSkillDir = path.join(destDir, skill.dirName);
+        fs.mkdirSync(targetSkillDir, { recursive: true });
+
+        const formattedContent = formatSkill(agent, skill.frontmatter, skill.markdown);
+        fs.writeFileSync(path.join(targetSkillDir, 'SKILL.md'), formattedContent, 'utf-8');
+        
+        console.log(`[${agent.toUpperCase()}] 技能已成功注册 => ${path.join(targetSkillDir, 'SKILL.md')}`);
+      }
+    } catch (err) {
+      console.warn(`\x1b[33m[警告] 无法为 ${agent} 注册技能，路径可能不可写: ${destDir} (错误: ${err.message})\x1b[0m`);
+    }
+  }
+
+  // 适配 Gemini / Antigravity (使用单一 markdown 文件放在 global_workflows 下)
+  try {
+    const destDir = agentPaths.gemini;
+    fs.mkdirSync(destDir, { recursive: true });
+    for (const skill of parsedSkills) {
+      const formattedContent = formatSkill('gemini', skill.frontmatter, skill.markdown);
+      const targetFilePath = path.join(destDir, `${skill.frontmatter.name || skill.dirName}.md`);
+      fs.writeFileSync(targetFilePath, formattedContent, 'utf-8');
+      console.log(`[GEMINI] 工作流已成功注册 => ${targetFilePath}`);
+    }
+  } catch (err) {
+    console.warn(`\x1b[33m[警告] 无法为 Gemini 注册工作流，路径可能不可写: ${agentPaths.gemini} (错误: ${err.message})\x1b[0m`);
+  }
+
+  // 适配 OpenCode (使用统一的 AGENTS.md 存放在 opencode 全局配置目录下)
+  try {
+    const destDir = agentPaths.opencode;
+    fs.mkdirSync(destDir, { recursive: true });
+    
+    // 合并所有的技能生成一份全局 AGENTS.md
+    let combinedAgentsMd = '# OpenCode 前端规范宪法 (AGENTS.md)\n\n';
+    for (const skill of parsedSkills) {
+      combinedAgentsMd += formatSkill('opencode', skill.frontmatter, skill.markdown) + '\n\n---\n\n';
+    }
+    
+    const targetFilePath = path.join(destDir, 'AGENTS.md');
+    fs.writeFileSync(targetFilePath, combinedAgentsMd, 'utf-8');
+    console.log(`[OPENCODE] 全局 AGENTS.md 已成功注册 => ${targetFilePath}`);
+  } catch (err) {
+    console.warn(`\x1b[33m[警告] 无法为 OpenCode 注册规则，路径可能不可写: ${agentPaths.opencode} (错误: ${err.message})\x1b[0m`);
+  }
+
+  console.log('\x1b[32m%s\x1b[0m', '>> 全局技能注册与同步成功！所有关联智能体已装载最新前端制定方案规范。');
+  return true;
+}

package/src/templates/index.js

@@ -0,0 +1,42 @@
+/**
+ * 针对各智能体格式，将原始 Frontmatter 和 Markdown 内容转换并包裹为符合其要求的技能文件
+ * @param {string} agentType 智能体类型 ('claude' | 'cursor' | 'codex' | 'gemini' | 'opencode')
+ * @param {object} frontmatter 包含 name, description, globs 等字段的元数据
+ * @param {string} markdown 核心的 markdown 指导说明
+ * @returns {string} 包装适配后的文件字符串
+ */
+export function formatSkill(agentType, frontmatter, markdown) {
+  // Cursor, Claude Code, Codex 对全局 SKILL.md 使用一致的 YAML Frontmatter 标准
+  if (['cursor', 'claude', 'codex'].includes(agentType)) {
+    const yamlHeader = [
+      '---',
+      `name: ${frontmatter.name || ''}`,
+      `description: ${frontmatter.description || ''}`,
+      'globs:',
+      ...(frontmatter.globs || []).map(glob => `  - "${glob}"`),
+      '---',
+      ''
+    ].join('\n');
+
+    return `${yamlHeader}${markdown}`;
+  }
+
+  // Gemini / Antigravity 适用于带 description frontmatter 的 markdown 格式
+  if (agentType === 'gemini') {
+    const yamlHeader = [
+      '---',
+      `description: ${frontmatter.description || ''}`,
+      '---',
+      ''
+    ].join('\n');
+    return `${yamlHeader}${markdown}`;
+  }
+
+  // OpenCode 等全局规则格式
+  if (agentType === 'opencode') {
+    return `# Global Rules: ${frontmatter.name || ''}\n\n${markdown}`;
+  }
+
+  // 默认直接返回内容
+  return markdown;
+}