WinJS Skills

WinJS 框架的 Agent Skills 集合，为不同的项目模板提供专门的开发指导、配置说明和最佳实践。

📦 包含的技能

技能	模板类型	技术栈	核心功能
winjs-app	移动端 H5	Vue 3 + Vite	REM 适配、VConsole、请求封装
winjs-huipro	企业级 Web	Vue 2 + Webpack + HUI	自定义 Router、TabsManagement、权限
winjs-hybrid	混合应用	Vue 3 + Vite + WebView	原生桥接、GmuJSAPI、容器跳转
winjs-pc	PC 端 Web	Vue 3 + Vite	PC 浏览器、无移动端适配

💾 安装

推荐方式：使用 npx skills 命令直接安装

# 安装 WinJS Skills 到 Cursor
npx skills add https://github.com/winjs-dev/skills

🚀 快速开始

识别项目模板

根据项目特征快速判断使用哪个技能：

你的项目是?
├─ 配置在 config/config.ts → 使用 winjs-huipro
└─ 配置在 .winrc.ts
   ├─ 有 convertToRem + wconsole → 使用 winjs-app
   ├─ 有 render 钩子 + GmuJSAPI → 使用 winjs-hybrid
   └─ 无 REM/VConsole → 使用 winjs-pc

查阅文档

每个技能包含以下文档：

skill-name/
├── SKILL.md                    # 核心指南（<120行，快速浏览）
└── references/                 # 详细参考文档
    ├── app-reference.md        # 模板配置速查
    ├── usage-reference.md      # 详细用法与规范
    ├── troubleshooting.md      # 常见问题排错
    └── docs-index.md           # 官方文档索引

推荐阅读顺序：

SKILL.md - 获取核心概念和快速参考
app-reference.md - 查看配置项和目录结构
usage-reference.md - 深入了解详细用法
troubleshooting.md - 遇到问题时查阅

📘 如何使用

零、安装技能（首次使用）

场景：首次在 Cursor 中使用 WinJS Skills

方式一：NPX 快速安装（推荐）

# 在终端中执行
npx skills add https://github.com/winjs-dev/skills

安装步骤：

1. 打开 Cursor IDE
   ↓
2. 打开终端（Terminal）
   ↓
3. 执行安装命令
   npx skills add https://github.com/winjs-dev/skills
   ↓
4. 等待安装完成（约 5-10 秒）
   ↓
5. 重启 Cursor（可选，建议）
   ↓
6. 安装完成！AI 已集成 WinJS Skills

验证安装：

# 打开任意 WinJS 项目
# 在 Cursor 中询问 AI：
"这是什么类型的 WinJS 项目？"

# AI 应该能够：
✅ 识别项目模板类型（app/huipro/hybrid/pc）
✅ 提供针对性的配置建议
✅ 引用具体的技能文档

方式二：手动克隆（离线/自定义）

# 1. 克隆仓库到本地
git clone https://github.com/winjs-dev/skills.git ~/.cursor/skills/winjs-skills

# 2. 在 Cursor 设置中配置技能路径（如需要）
# Settings → Extensions → Cursor Skills → Add Local Path
# 添加: ~/.cursor/skills/winjs-skills

# 3. 重启 Cursor

安装后的优势

功能	说明
自动识别	AI 自动检测项目是 app/huipro/hybrid/pc
智能提示	根据模板提供精准的代码提示
配置帮助	快速查询 `.winrc.ts` 或 `config/config.ts` 配置项
问题排查	自动引用 `troubleshooting.md` 解决方案
文档查询	即时访问 4 个技能的完整文档

一、开发者使用指南

1. 新建项目时

场景：使用 create-win 脚手架创建新项目

# 1. 创建项目
npx create-win my-project

# 2. 选择模板类型
? 选择项目模板:
  ❯ app     - 移动端 H5 应用
    huipro  - 企业级后台管理
    hybrid  - 混合应用（WebView）
    pc      - PC 端 Web 应用

# 3. 进入项目目录
cd my-project

# 4. 查阅对应技能文档
# 根据选择的模板，阅读对应的 SKILL.md

对应技能文档：

选择 app → 阅读 winjs-app/SKILL.md
选择 huipro → 阅读 winjs-huipro/SKILL.md
选择 hybrid → 阅读 winjs-hybrid/SKILL.md
选择 pc → 阅读 winjs-pc/SKILL.md

2. 接手现有项目时

场景：接手他人开发的 WinJS 项目

识别步骤：

# 步骤1: 查看配置文件位置
ls -la | grep -E "(\.winrc|config)"

# 步骤2: 根据配置文件判断模板

判断流程：

是否存在 config/config.ts?
├─ 是 → winjs-huipro 模板
│      阅读: ./skills/winjs-huipro/SKILL.md
│
└─ 否 → 检查 .winrc.ts 或 .winrc.js
   ├─ 包含 convertToRem: true + wconsole 插件
   │  → winjs-app 模板（移动端）
   │     阅读: ./skills/winjs-app/SKILL.md
   │
   ├─ 包含 render(oldRender) 钩子 或 GmuJSAPI
   │  → winjs-hybrid 模板（混合应用）
   │     阅读: ./skills/winjs-hybrid/SKILL.md
   │
   └─ 无 REM 配置、无 VConsole
      → winjs-pc 模板（PC 端）
         阅读: ./skills/winjs-pc/SKILL.md

快速识别特征：

特征	对应模板
`config/config.ts` 配置文件	winjs-huipro
`convertToRem` + `wconsole`	winjs-app
`GmuJSAPI` / `Harmony JSApi`	winjs-hybrid
无 REM、无 VConsole、纯 PC 端	winjs-pc

3. 开发过程中

场景：开发时需要查阅配置、用法或解决问题

常见任务与对应文档：

任务	查阅文档	示例
修改配置	`app-reference.md` → "配置项说明"	修改 API 地址、开启 Mock
添加页面/路由	`usage-reference.md` → "路由约定"	创建新页面、配置路由
编写 API 请求	`usage-reference.md` → "请求封装"	定义 service、处理响应
调试样式（移动端）	`usage-reference.md` → "REM 适配"	设置设计稿尺寸、像素转换
对接原生 API（Hybrid）	`usage-reference.md` → "原生桥接"	调用 GmuJSAPI、Light SDK
配置子系统（HuiPro）	`usage-reference.md` → "主子系统"	创建 index.pro.js
遇到报错	`troubleshooting.md`	查看错误码、解决方案
查找官方文档	`docs-index.md`	定位对应的官方文档链接

查阅流程：

遇到问题 → 确定模板类型 → 进入对应技能目录 → 按需查阅

示例：winjs-app 项目需要调整 REM 适配
1. 进入 skills/winjs-app/
2. 打开 SKILL.md，查看"核心配置"章节
3. 如需详细说明，打开 references/usage-reference.md
4. 搜索"REM 适配"或"convertToRem"

4. 排查问题时

场景：开发遇到错误或异常

排查步骤：

# 步骤1: 确认模板类型（见"接手现有项目"）
# 步骤2: 打开对应的 troubleshooting.md
# 步骤3: 搜索错误关键词

# 示例：HuiPro 项目路由报错
cd skills/winjs-huipro/references/
grep -i "router" troubleshooting.md

# 示例：Hybrid 项目原生 API 调用失败
cd skills/winjs-hybrid/references/
grep -i "GmuJSAPI" troubleshooting.md

常见问题速查：

问题类型	优先查阅	关键词
构建失败	`troubleshooting.md` → "构建相关"	build、compile、webpack
路由不生效	`troubleshooting.md` → "路由相关"	router、route、跳转
请求失败 / 跨域	`troubleshooting.md` → "请求相关"	request、cors、proxy
样式适配问题（移动）	`troubleshooting.md` → "样式相关"	rem、postcss、viewport
原生 API 调用失败	`troubleshooting.md` → "原生桥接相关"	GmuJSAPI、JSBridge
TypeScript 类型错误	`usage-reference.md` → "TypeScript"	type、interface、泛型

二、AI 助手使用指南

1. 自动触发（AI 专用）

当用户提及以下关键词时，AI 应自动加载对应技能：

winjs-app 触发词：

create-win app、移动端 H5、REM 适配
VConsole、wconsole 插件、convertToRem

winjs-huipro 触发词：

create-win huipro、企业级后台、HUI 组件
TabsManagement、config/config.ts、自定义 Router

winjs-hybrid 触发词：

create-win hybrid、混合应用、WebView
GmuJSAPI、Harmony JSApi、Light SDK、原生桥接

winjs-pc 触发词：

create-win pc、PC 端、桌面浏览器

2. 查阅流程（AI 专用）

三步法则：

第一步：识别模板
  ↓
  分析用户项目特征（配置文件、package.json、目录结构）
  ↓
  确定使用哪个技能（app/huipro/hybrid/pc）

第二步：加载核心文档
  ↓
  读取对应的 SKILL.md
  ↓
  获取概览、配置、目录结构

第三步：按需深入
  ↓
  根据用户问题，选择性读取 references/ 中的详细文档
  ↓
  app-reference.md      → 查配置项
  usage-reference.md    → 查用法规范
  troubleshooting.md    → 查问题解决
  docs-index.md         → 查官方文档

示例对话：

用户："我的 WinJS App 项目怎么修改 API 地址？"

AI 处理流程：
1. 识别：关键词 "WinJS App" → 确定为 winjs-app 模板
2. 读取：skills/winjs-app/SKILL.md → 查看"核心配置"章节
3. 定位：找到 .winrc.ts 中的 appConfig.API_HOME 配置
4. 回答：
   "在 .winrc.ts 中修改 appConfig.API_HOME：
   
   export default defineConfig({
     appConfig: {
       API_HOME: 'https://your-new-api.com'
     }
   })"

3. 最佳实践（AI 专用）

优先级规则：

先读 SKILL.md（核心文档，必读）
按需读 references（深入了解，选读）
避免重复查询（已知信息不重复调用工具）
精确引用（回答时引用具体文件和行号）

响应模式：

用户问题 → 快速判断 → 精准响应

问题类型：
├─ 配置类 → 直接给出配置代码片段
├─ 用法类 → 给出示例代码 + 说明
├─ 排错类 → 给出诊断步骤 + 解决方案
└─ 概念类 → 简要解释 + 相关文档链接

禁止行为：

❌ 不要编造不存在的配置项
❌ 不要混淆不同模板的配置（如把 HuiPro 的配置用到 App）
❌ 不要在 Vue 2 项目中使用 Vue 3 API（注意版本）
❌ 不要忽略模板特有的约定（如 HuiPro 的自定义 Router）

详见：

AGENT.md - AI 代理快速参考（135行，必读）
CLAUDE.md - Claude 详细使用教程（282行，推荐）

三、实际应用示例

示例 1：创建移动端 H5 项目

# 1. 创建项目
npx create-win my-h5-app
# 选择: app

# 2. 查阅技能文档
# 阅读: skills/winjs-app/SKILL.md

# 3. 修改配置
# 编辑 .winrc.ts
export default defineConfig({
  convertToRem: {
    enabled: true,
    rootValue: 75  // 750 设计稿
  },
  appConfig: {
    API_HOME: 'https://api.myapp.com',
    IS_OPEN_VCONSOLE: true
  }
})

# 4. 添加页面
# 在 src/pages/ 下创建 user/index.vue

# 5. 编写请求
# 在 src/services/ 下创建 user.js

# 6. 启动开发
win dev

查阅文档：

配置 REM → skills/winjs-app/references/usage-reference.md 搜索 "convertToRem"
编写请求 → skills/winjs-app/references/usage-reference.md 搜索 "请求封装"

示例 2：维护企业后台项目

# 1. 识别项目类型
ls config/config.ts  # 存在 → winjs-huipro

# 2. 查阅技能文档
# 阅读: skills/winjs-huipro/SKILL.md

# 3. 添加子系统
# 创建 src/projects/my-subsystem/index.pro.js

# 4. 配置路由
# 使用 Router 3.x API（Vue 2）

# 5. 使用 HUI 组件
import { HButton, HTable } from '@hui-pro/components'

# 6. 启动开发
win dev

查阅文档：

子系统配置 → skills/winjs-huipro/references/usage-reference.md 搜索 "主子系统"
自定义 Router → skills/winjs-huipro/references/usage-reference.md 搜索 "自定义 Router"

示例 3：开发混合应用

# 1. 创建项目
npx create-win my-hybrid-app
# 选择: hybrid

# 2. 查阅技能文档
# 阅读: skills/winjs-hybrid/SKILL.md

# 3. 配置原生桥接
# 在 src/app.js 中
export function render(oldRender) {
  if (window.GmuJSAPI) {
    // 原生环境已就绪
    oldRender()
  } else {
    // 等待原生就绪事件
    document.addEventListener('GmuJSAPIReady', () => {
      oldRender()
    })
  }
}

# 4. 调用原生 API
import { GmuJSAPI } from '@winner-fed/harmony-jsapi'

GmuJSAPI.navigateTo({
  url: '/pages/detail',
  params: { id: 123 }
})

# 5. 启动开发
win dev

查阅文档：

原生桥接 → skills/winjs-hybrid/references/usage-reference.md 搜索 "GmuJSAPI"
render 钩子 → skills/winjs-hybrid/SKILL.md 搜索 "应用入口"

四、文档更新与维护

文档版本：随 WinJS 框架同步更新

检查更新：

# 查看最新版本
git pull origin main

# 查看更新日志
cat .claude-plugin/marketplace.json | grep -A 10 "changelog"

反馈问题：

提交 Issue：winjs-dev/skills/issues
提出改进建议：Pull Request

📖 技能详情

winjs-app（移动端 H5）

适用场景：

create-win app 模板创建的项目
需要 REM 适配的移动端 H5 应用
需要 VConsole 调试工具
使用 Vue 3 + Vue Router 4 + Vite

核心配置：

// .winrc.ts
export default defineConfig({
  convertToRem: { enabled: true },
  plugins: ['@winner-fed/plugin-request', '@winner-fed/plugin-wconsole'],
  appConfig: {
    API_HOME: 'https://api.example.com',
    IS_OPEN_VCONSOLE: true
  }
})

查看详细文档 →

winjs-huipro（企业级 Web）

适用场景：

create-win huipro 模板创建的项目
企业级后台管理系统
需要自定义 Router、Vuex 状态管理
使用 TabsManagement 页签管理
主子系统架构

核心特点：

配置在 config/config.ts（非 .winrc）
Vue 2.6 + Vue Router 3.x + Vuex
自定义 Router 实例（src/router/）
HUI 企业级组件库

查看详细文档 →

winjs-hybrid（混合应用）

适用场景：

create-win hybrid 模板创建的项目
运行在 WebView 中的混合应用
需要对接原生 API（鸿蒙/券商）
使用 Harmony JSApi 或 Light SDK

核心特点：

原生桥接（GmuJSAPI、Light SDK）
render(oldRender) 钩子控制渲染时序
支持 WebView 容器内跳转（navigateTo）
支持离线包配置

查看详细文档 →

winjs-pc（PC 端 Web）

适用场景：

create-win pc 模板创建的项目
PC 桌面浏览器应用
不需要移动端适配功能

核心特点：

无 REM 适配、无 VConsole
专注 PC 浏览器（Chrome、Firefox、Safari、Edge）
使用 Vite 构建，性能优化

查看详细文档 →

🔍 功能对比

功能特性	app	huipro	hybrid	pc
配置文件	`.winrc.ts`	`config/config.ts`	`.winrc.ts`	`.winrc.ts`
Vue 版本	3	2.6	3/2.7	3/2.7
构建工具	Vite	Webpack	Vite	Vite
Router	约定式	自定义	约定式	约定式
REM 适配	✅	❌	✅	❌
VConsole	✅	❌	✅	❌
原生桥接	❌	❌	✅	❌
TabsManagement	❌	✅	❌	❌
主子系统	❌	✅	❌	❌

📚 AI 使用指南

如果你是 AI 编码助手，请查阅：

AGENT.md - AI 代理快速参考指南（135行）
CLAUDE.md - Claude AI 详细使用教程（282行）

这些文档包含：

自动触发场景识别
文档查阅优先级
常见任务处理流程
示例对话和最佳实践

🛠️ 常用命令

所有模板通用：

win dev          # 启动开发服务器
win build        # 生产构建
win preview      # 预览构建结果
win cache        # 清理缓存
npm run lint     # 代码检查
npm run format   # 代码格式化

HuiPro 特有命令：

win huipro       # 子系统构建
win see          # 构建SEE包

📝 常见问题

如何选择合适的模板？

需求	推荐模板
移动端 H5，需要 REM 适配	winjs-app
企业后台，需要权限管理	winjs-huipro
混合应用，对接原生 API	winjs-hybrid
PC 端网站，桌面浏览器	winjs-pc

配置文件在哪里？

winjs-app / hybrid / pc: .winrc.ts 或 .winrc.js
winjs-huipro: config/config.ts

如何区分 Vue 2 和 Vue 3 项目？

Vue 2.6: winjs-huipro（使用 Router 3.x API）
Vue 3: winjs-app / hybrid / pc（使用 Router 4.x API）

遇到问题怎么办？

确定项目使用的模板类型
查阅对应技能的 troubleshooting.md
参考 docs-index.md 定位官方文档
查看 usage-reference.md 的详细说明

🔗 相关资源

📂 项目结构

skills/
├── README.md                   # 本文件
├── AGENT.md                    # AI 代理快速参考
├── CLAUDE.md                   # Claude 使用教程
├── DOCS_INDEX.md               # 完整文档索引
├── .claude-plugin.md           # 插件配置说明
├── .claude-plugin/             # 插件配置目录
│   └── marketplace.json       # Marketplace 配置
└── skills/                     # 技能目录
    ├── winjs-app/              # App 模板技能
    │   ├── SKILL.md
    │   └── references/
    ├── winjs-huipro/           # HuiPro 模板技能
    │   ├── SKILL.md
    │   └── references/
    ├── winjs-hybrid/           # Hybrid 模板技能
    │   ├── SKILL.md
    │   └── references/
    └── winjs-pc/               # PC 模板技能
        ├── SKILL.md
        └── references/

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这些技能文档。

贡献指南

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

文档规范

保持 SKILL.md 文件在 500 行以内
使用中文编写文档
遵循现有的文档结构和格式
提供实际的代码示例

📮 联系方式

GitHub Issues: winjs-dev/skills/issues
官方文档: winjs-docs

提示: 这些技能随 WinJS 框架更新而更新，建议定期检查是否有新版本。

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.claude-plugin		.claude-plugin
skills		skills
.gitignore		.gitignore
AGENT.md		AGENT.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

WinJS Skills

📦 包含的技能

💾 安装

🚀 快速开始

识别项目模板

查阅文档

📘 如何使用

零、安装技能（首次使用）

方式一：NPX 快速安装（推荐）

方式二：手动克隆（离线/自定义）

安装后的优势

一、开发者使用指南

1. 新建项目时

2. 接手现有项目时

3. 开发过程中

4. 排查问题时

二、AI 助手使用指南

1. 自动触发（AI 专用）

2. 查阅流程（AI 专用）

3. 最佳实践（AI 专用）

三、实际应用示例

示例 1：创建移动端 H5 项目

示例 2：维护企业后台项目

示例 3：开发混合应用

四、文档更新与维护

📖 技能详情

winjs-app（移动端 H5）

winjs-huipro（企业级 Web）

winjs-hybrid（混合应用）

winjs-pc（PC 端 Web）

🔍 功能对比

📚 AI 使用指南

🛠️ 常用命令

📝 常见问题

如何选择合适的模板？

配置文件在哪里？

如何区分 Vue 2 和 Vue 3 项目？

遇到问题怎么办？

🔗 相关资源

📂 项目结构

📄 许可证

🤝 贡献

贡献指南

文档规范

📮 联系方式

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages