@agile-team/wl-skills-kit 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +33 -1
  3. package/files/.github/copilot-instructions.md +53 -8
  4. package/files/.github/docs/wl-skills-kit.md +266 -266
  5. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## [1.1.2] - 2026-04-09
4
+
5
+ ### 新增：Skills 自动调度注册表
6
+
7
+ - `copilot-instructions.md` 末尾新增 **Skills 自动调度** 章节，包含：
8
+ - Skill 注册表（触发关键词 → 必须读取的 SKILL.md 文件映射）
9
+ - 完整流水线（prototype-scan → api-contract → page-codegen → menu-sync）
10
+ - 单独使用模式（只触发单个 Skill）
11
+ - 组件文档按需查阅表 + 领域样例参考表
12
+ - 所有编辑器配置文件（8 个）均继承此注册表，实现 **全编辑器 Skill 自动调度**
13
+ - README 更新：Skill 识别列从 "⚠️ 需手动引用" → "✅ 通过注册表自动 read_file"
14
+
15
+ ## [1.1.1] - 2026-04-09
16
+
17
+ ### 修复
18
+
19
+ - 修复 wl-skills-kit.md 中 10 处 `@jhlc/wl-skills-kit` 过时包名引用 → `@agile-team/wl-skills-kit`
20
+ - README 新增「多编辑器 / AI 工具支持」章节，详细说明 8 个编辑器的使用姿势差异
21
+ - License 从 MIT 改为 UNLICENSED（内部使用）
22
+
3
23
  ## [1.1.0] - 2026-04-09
4
24
 
5
25
  ### 新增：多编辑器支持（v1.1）
package/README.md CHANGED
@@ -206,6 +206,38 @@ npx @agile-team/wl-skills-kit
206
206
 
207
207
  ---
208
208
 
209
+ ## 多编辑器 / AI 工具支持
210
+
211
+ 安装后自动生成 **8 个编辑器配置文件**，内容统一来自 `copilot-instructions.md`（单一源头），确保所有 AI 工具读取到相同的项目规范。
212
+
213
+ ### 各工具配置一览
214
+
215
+ | AI 工具 | 配置文件路径 | 规范加载 | Skill 自动调度 | 备注 |
216
+ |---------|-------------|---------|---------------|------|
217
+ | **GitHub Copilot** (VS Code) | `.github/copilot-instructions.md` | ✅ 自动 | ✅ 原生 Skill 识别 + 注册表双保险 | **主力工具，体验最完整** |
218
+ | **Cursor** | `.cursorrules` + `.cursor/rules/conventions.mdc` | ✅ 自动 | ✅ 通过注册表自动 `read_file` | `.mdc` 带 `alwaysApply: true` 前缀 |
219
+ | **Windsurf (Cascade)** | `.windsurfrules` | ✅ 自动 | ✅ 通过注册表自动 `read_file` | 规范内嵌调度指令 |
220
+ | **Kiro** | `.kiro/steering/conventions.md` | ✅ 自动 | ✅ 通过注册表自动 `read_file` | steering/ 下的 md 自动加载 |
221
+ | **Trae** | `.trae/rules/conventions.md` | ✅ 自动 | ✅ 通过注册表自动 `read_file` | rules/ 下的 md 自动加载 |
222
+ | **Claude Code / CLI** | `CLAUDE.md` | ✅ 自动 | ✅ 通过注册表自动 `read_file` | 也支持 `@import` 语法 |
223
+ | **Roo Code / Cline** | `.clinerules` | ✅ 自动 | ✅ 通过注册表自动 `read_file` | 支持 tool_use 读文件 |
224
+ | **AGENTS.md 兼容** | `AGENTS.md` | ✅ 自动 | ✅ 通过注册表自动 `read_file` | Linux Foundation 通用标准，兜底 |
225
+
226
+ ### Skill 自动调度机制（v1.1.2+）
227
+
228
+ 所有编辑器配置文件均由 `copilot-instructions.md` 生成，其中内嵌了 **Skills 自动调度注册表**。
229
+ 该注册表以强制指令形式告知 AI：
230
+
231
+ 1. **触发关键词匹配** — 用户说"生成页面"/"扫描原型"/"接口约定"等关键词时，AI 必须先 `read_file` 对应的 `SKILL.md`
232
+ 2. **完整流水线** — 用户提供原型/详设并要求批量生成时，按 prototype-scan → api-contract → page-codegen → menu-sync 顺序依次执行
233
+ 3. **单独使用** — 用户只说"帮我生成客户档案页面"时，只读取 page-codegen 的 SKILL.md，不必跑完整流水线
234
+
235
+ 这意味着 **所有支持 `read_file` / tool_use 的 AI 工具都能自动调度 Skill**，无需手动引用。
236
+
237
+ > **总结**：v1.1.2 起，**编码规范 + Skill 调度** 均为全编辑器自动加载（零配置）。各工具唯一的区别仅在于原生 Skill 识别（Copilot 独有） vs 注册表驱动的 `read_file` 调度（通用）。
238
+
239
+ ---
240
+
209
241
  ## 安装行为说明
210
242
 
211
243
  | ✅ 会做 | ❌ 不会做 |
@@ -325,4 +357,4 @@ npx . --dry-run # 本地预览
325
357
 
326
358
  ## License
327
359
 
328
- MIT
360
+ UNLICENSED — 内部使用，未授权外部分发。
package/files/.github/copilot-instructions.md CHANGED
@@ -198,14 +198,59 @@ onMounted(() => select());
198
198
  - ❌ 手写查询表单/工具栏/分页（用 BaseQuery/BaseToolbar/jh-pagination）
199
199
  - ❌ 每个页面重复写弹窗组件（优先用 `c_modal` 等局部公共组件）
200
200
 
201
- ## Axure → Vue 生成流程
201
+ ## AI Skills 自动调度（强制执行 — 所有 AI 编辑器/模型通用）
202
202
 
203
- 详见 `.github/skills/` 下的 5 个 Skill：
203
+ 本项目内置 5 个 Skill 文件，覆盖「原型/详设 → 可运行页面 → 菜单注册」完整流程。
204
+ **执行以下任何任务前，必须先用工具读取（read_file）对应的 SKILL.md，读取完成前禁止生成任何代码或输出。**
204
205
 
205
- 1. **prototype-scan** — 解析 Axure HTML → 页面清单
206
- 2. **convention-extract** — 项目规范提炼（已固化，新项目时使用）
207
- 3. **api-contract** — 页面清单 → api.md 接口约定
208
- 4. **page-codegen** — 生成 index.vue + data.ts + index.scss + api.md
209
- 5. **menu-sync** — 将 pages.ts 页面同步到后端菜单表（Phase 1：AI 调 `/system/menu/save`；Phase 2：`pnpm run menu:push`）
206
+ ### Skill 注册表
210
207
 
211
- > 完整使用步骤及精度技巧见 `.github/docs/use-skill.md`
208
+ | 触发场景（用户意图关键词） | 必须读取的文件 | Skill 名称 |
209
+ |---|---|---|
210
+ | 扫描原型、解析原型、页面清单、原型分析、详设文档 | `.github/skills/prototype-scan/SKILL.md` | prototype-scan |
211
+ | 接口约定、api.md、字段定义、前后端对齐、接口设计 | `.github/skills/api-contract/SKILL.md` | api-contract |
212
+ | 生成页面、创建页面、代码生成、vue页面、按原型生成 | `.github/skills/page-codegen/SKILL.md`（主文件会指示继续读取对应的 `TPL-*.md` 模板） | page-codegen |
213
+ | 创建菜单、注册菜单、同步菜单、补菜单 | `.github/skills/menu-sync/SKILL.md` | menu-sync |
214
+ | 提炼规范、项目规范、编码规范扫描 | `.github/skills/convention-extract/SKILL.md` | convention-extract |
215
+
216
+ ### 完整流水线（原型/详设 → 页面 → 菜单）
217
+
218
+ 当用户提供原型文件或详设文档并要求批量生成页面时，按以下顺序依次执行：
219
+
220
+ ```
221
+ Step 1 → 读取 prototype-scan/SKILL.md → 执行原型扫描 → 输出 page-spec
222
+ Step 2 → 读取 api-contract/SKILL.md → 生成 api.md 接口约定
223
+ Step 3 → 读取 page-codegen/SKILL.md → 逐页生成代码（每页读取对应 TPL-*.md）
224
+ Step 4 → 读取 menu-sync/SKILL.md → 注册菜单到后端
225
+ ```
226
+
227
+ 每个 Step 开始前读取对应 SKILL.md，**前一个 Step 完成后再进入下一个**。
228
+ 上一步的输出（如 page-spec）直接作为下一步的输入，无需用户中间干预。
229
+
230
+ ### 单独使用
231
+
232
+ 用户也可以只执行单个 Skill（如只说"帮我生成客户档案页面"），此时只需读取对应的 SKILL.md，不必执行完整流水线。
233
+
234
+ ### 组件文档按需查阅
235
+
236
+ 生成代码过程中如需了解组件用法，读取 `docs/` 下对应文档：
237
+
238
+ | 组件 | 文档路径 |
239
+ |------|---------|
240
+ | BaseQuery / BaseTable / BaseToolbar | `src/components/remote/BaseQuery/README.md` 等 |
241
+ | jh-select / jh-date / jh-pagination 等 | `docs/jh-select.md` / `docs/jh-date.md` 等 |
242
+ | c_formModal / c_formSections / c_listModal | `src/components/local/c_formModal/README.md` 等 |
243
+ | AbstractPageQueryHook 最佳实践 | `docs/page-query-hook-best-practices.md` |
244
+ | HTTP 请求工具 | `docs/request.md` |
245
+
246
+ ### 领域样例参考
247
+
248
+ 首次生成某类页面时，可读取 `demo/` 下的对应样例学习实际写法：
249
+
250
+ | 模板类型 | 样例路径 |
251
+ |---------|---------|
252
+ | LIST（标准列表） | `demo/produce/aiflow/mmwr-customer-archive/` |
253
+ | FORM_ROUTE（复杂表单） | `demo/produce/aiflow/mmwr-customer-apply-add-form/` |
254
+ | CHANGE_HISTORY（变更历史） | `demo/produce/aiflow/mmwr-customer-apply-change-history/` |
255
+ | DETAIL_TABS（详情Tab） | `demo/produce/aiflow/mmwr-customer-detail/` |
256
+ | MASTER_DETAIL（上下分栏） | `demo/sale/demo/metallurgical-spec/` |
package/files/.github/docs/wl-skills-kit.md CHANGED
@@ -1,266 +1,266 @@
1
- # wl-skills-kit — AI Skill 模板包
2
-
3
- > 统一维护、一键分发：AI 指令 + 组件文档 + 通用组件 + 领域样例。
4
- > 安装即导入，无副作用，各项目通过 `npx @jhlc/wl-skills-kit` 同步更新。
5
-
6
- ---
7
-
8
- ## 一、定位
9
-
10
- **wl-skills-kit** 是公司前端 AI 生态的基础设施包。
11
-
12
- | 是什么 | 不是什么 |
13
- | ---------------------------------------- | ----------------------------------- |
14
- | 文件模板包，安装后按目录结构导入项目 | 不是运行时依赖 |
15
- | AI 指令 + 文档 + 组件 + 样例的统一维护源 | 不修改 package.json / node_modules |
16
- | 各项目同步更新的唯一通道 | 不执行 postinstall / 不删除任何文件 |
17
-
18
- **一句话**：`npx @jhlc/wl-skills-kit` = 把模板文件复制到你的项目。完毕。
19
-
20
- ---
21
-
22
- ## 二、包目录结构
23
-
24
- ```
25
- @jhlc/wl-skills-kit/
26
- ├── package.json ← name: "@jhlc/wl-skills-kit"
27
- ├── README.md
28
- ├── CHANGELOG.md
29
- ├── bin/
30
- │ └── wl-skills.js ← CLI 入口（文件拷贝 + 进度提示）
31
- │
32
- └── files/ ← 1:1 映射到目标项目根目录
33
- │
34
- ├── .github/ ← ① AI 指令（核心）
35
- │ ├── copilot-instructions.md ← 项目规范总纲
36
- │ ├── skills/
37
- │ │ ├── prototype-scan/SKILL.md ← 原型扫描
38
- │ │ ├── api-contract/SKILL.md ← 接口约定
39
- │ │ ├── page-codegen/ ← 页面代码生成
40
- │ │ │ ├── SKILL.md ← 主规则（~825 行）
41
- │ │ │ └── TPL-*.md ← 9 个模板（LIST / FORM-ROUTE / MASTER-DETAIL /
42
- │ │ │ TREE-LIST / DETAIL-TABS / CHANGE-HISTORY /
43
- │ │ │ RECORD-FORM / OPERATION-STATION / DRIVEN）
44
- │ │ ├── menu-sync/
45
- │ │ │ ├── SKILL.md ← 菜单同步
46
- │ │ │ └── env/guide.md ← env.local.json 配置说明（json 本身不分发）
47
- │ │ └── convention-extract/SKILL.md ← 规范提炼
48
- │ └── docs/
49
- │ ├── use-skill.md ← 使用 + 移植一站式指南
50
- │ ├── menu-sync-design.md ← 菜单同步方案设计
51
- │ ├── SYS_MENU_INFO.md ← 菜单注册记录模板
52
- │ └── wl-skills-kit.md ← 本文档
53
- │
54
- ├── docs/ ← ② 组件文档（12 个 md）
55
- │ ├── request.md ← HTTP 请求工具
56
- │ ├── page-query-hook-best-practices.md
57
- │ ├── jh-select.md / jh-date.md / jh-date-range.md
58
- │ ├── jh-drag-row.md / jh-pagination.md / jh-file-upload.md
59
- │ └── jh-text.md / jh-user-picker.md / jh-dept-picker.md / jh-picker.md
60
- │
61
- ├── src/
62
- │ ├── components/ ← ③ 通用组件
63
- │ │ ├── global/ ← C_Splitter / C_Tree / C_TagStatus
64
- │ │ │ C_ParentView / C_SvgIcon / C_RightToolbar
65
- │ │ ├── local/ ← c_formModal / c_formSections
66
- │ │ │ c_listModal / c_spliterTitle
67
- │ │ └── remote/ ← BaseQuery / BaseTable / BaseToolbar
68
- │ │ BaseForm / AGGrid（仅 README）
69
- │ └── types/page.ts ← ④ 类型桶文件
70
- │
71
- └── demo/ ← ⑤ 领域样例（AI 学习 + 开发参考）
72
- ├── README.md ← 样例索引 + 模板类型标注
73
- ├── produce/
74
- │ └── aiflow/ ← 生产域 8 个页面
75
- │ ├── mmwr-customer-archive/ ← LIST + Tabs + c_formModal
76
- │ ├── mmwr-temp-customer-archive/ ← LIST
77
- │ ├── mmwr-customer-apply-add/ ← LIST
78
- │ ├── mmwr-customer-apply-add-form/ ← FORM_ROUTE
79
- │ ├── mmwr-customer-apply-change/ ← LIST
80
- │ ├── mmwr-customer-apply-change-form/ ← FORM_ROUTE
81
- │ ├── mmwr-customer-apply-change-history/ ← CHANGE_HISTORY
82
- │ └── mmwr-customer-detail/ ← DETAIL_TABS
83
- └── sale/
84
- └── demo/ ← 销售域 5 个页面（平台默认样例）
85
- ├── domestic-trade-order/ ← LIST 标准列表
86
- ├── metallurgical-spec/ ← MASTER_DETAIL 上下分栏
87
- ├── add-demo/ ← FORM_ROUTE（c_formSections）
88
- ├── billet-flame-cut-plan/ ← LIST 变体
89
- └── heat-batch-return/ ← LIST + 自定义弹窗
90
- ```
91
-
92
- > `files/` 下所有内容按原始路径写入项目根目录。**仅此而已，无其他逻辑。**
93
-
94
- ### 不分发的内容
95
-
96
- | 路径 | 原因 |
97
- | ------------------------------------------- | ---------------------------------------- |
98
- | `src/components/template/*` | 高阶封装，v2.0 稳定后再纳入 |
99
- | `src/components/local/c_customerTabs/` | 客户域专用 |
100
- | `src/components/local/c_applyDetailDialog/` | 客户域专用 |
101
- | `src/components/local/c_actionModal/` | 客户域专用 |
102
- | `menu-sync/env/env.local.json` | 含 Token，各项目本地维护（已 gitignore） |
103
-
104
- ---
105
-
106
- ## 三、使用方式
107
-
108
- ```bash
109
- # 安装 / 初始化（首次）
110
- npx @jhlc/wl-skills-kit
111
-
112
- # 同步更新（拉取最新模板）
113
- npx @jhlc/wl-skills-kit@latest
114
-
115
- # 预览变更（不写入，仅输出文件列表）
116
- npx @jhlc/wl-skills-kit --dry-run
117
- ```
118
-
119
- | ✅ 做什么 | ❌ 不做什么 |
120
- | ------------------------------ | -------------------- |
121
- | 写入 .github/ docs/ src/ demo/ | 不修改 package.json |
122
- | 覆盖同名文件 | 不修改 node_modules/ |
123
- | 创建不存在的目录 | 不执行 postinstall |
124
- | | 不删除任何文件 |
125
-
126
- ### 安全路径（不会被覆盖）
127
-
128
- 以下路径不在分发范围内，本地修改永远安全：
129
-
130
- ```
131
- .github/skills/my-domain-skill/ ← 自定义 Skill（非内置名）
132
- .github/docs/my-domain-doc.md ← 自定义文档
133
- src/components/local/my_custom/ ← 自定义组件
134
- src/views/ ← 业务页面
135
- mock/ ← Mock 数据
136
- ```
137
-
138
- | 修改类型 | 做法 |
139
- | -------- | --------------------------------------------------- |
140
- | 通用改进 | **提 PR 到 wl-skills-kit 仓库**，合并后所有项目受益 |
141
- | 领域专有 | 放在上述安全路径，不会被覆盖 |
142
-
143
- ---
144
-
145
- ## 四、多编辑器支持
146
-
147
- v1.0 聚焦 **GitHub Copilot**（`.github/` 目录即完整配置）。
148
-
149
- v1.1 实现：CLI 安装时自动从 `.github/copilot-instructions.md` **动态生成**各编辑器配置文件。单一源头，更新 `copilot-instructions.md` 后重新运行即同步所有编辑器配置。
150
-
151
- | 编辑器 | 配置路径 | 状态 |
152
- | ------------------ | -------------------------------------------------------------- | ------- |
153
- | **GitHub Copilot** | `.github/copilot-instructions.md` + `skills/` | ✅ v1.0 |
154
- | **Cursor** | `.cursorrules` + `.cursor/rules/conventions.mdc` (alwaysApply) | ✅ v1.1 |
155
- | **Windsurf** | `.windsurfrules` | ✅ v1.1 |
156
- | **Kiro** | `.kiro/steering/conventions.md` | ✅ v1.1 |
157
- | **Trae** | `.trae/rules/conventions.md` | ✅ v1.1 |
158
- | **Claude Code** | `CLAUDE.md` | ✅ v1.1 |
159
- | **Roo / Cline** | `.clinerules` | ✅ v1.1 |
160
- | **AGENTS.md** | `AGENTS.md`（Linux Foundation 标准，通用兜底） | ✅ v1.1 |
161
-
162
- > **原则**：AGENTS.md 是跨工具兜底标准，新工具出来大概率支持它。
163
-
164
- ---
165
-
166
- ## 五、发布策略
167
-
168
- | 方式 | 场景 | 命令 |
169
- | -------------------- | ----------- | ---------------------------------------------------- |
170
- | **npm 公有**（优先） | 公开发布 | `npm publish --access public` |
171
- | **私有 npm**（备选） | 内网团队 | `npm config set @jhlc:registry http://npm.nisco.cn/` |
172
- | **Git 直装** | 无 npm 仓库 | `npx git+http://git.nisco.cn/PSQF/wl-skills-kit.git` |
173
- | **离线 tgz** | 隔离网络 | `npm pack` → `npx ./jhlc-wl-skills-kit-x.x.x.tgz` |
174
-
175
- ---
176
-
177
- ## 六、贡献指南
178
-
179
- ### 可贡献内容
180
-
181
- | 类型 | 示例 | 贡献者 |
182
- | ---------- | ----------------------------------- | -------------- |
183
- | Skill 修复 | 修复 page-codegen 生成 bug | 任何使用者 |
184
- | 组件文档 | 新增 jh-xxx 文档 | 平台组件开发者 |
185
- | 领域样例 | `demo/{domain}/{submodule}/{page}/` | 各域开发者 |
186
- | 通用组件 | 新增 c_xxxModal | 架构组 |
187
-
188
- ### 样例贡献规范
189
-
190
- 每个样例目录必须包含：
191
-
192
- | 文件 | 必须 | 说明 |
193
- | ------------ | ---- | ---------------------------------------- |
194
- | `index.vue` | ✅ | 视图层 |
195
- | `data.ts` | ✅ | 逻辑层（必须用 `createPage()` 标准模式） |
196
- | `index.scss` | ✅ | 样式层 |
197
- | `api.md` | 可选 | 有 API 约定时提供 |
198
-
199
- **质量要求**：使用 Mock 数据（不依赖后端即可运行），脱敏处理（无真实手机号、客户名等）。
200
-
201
- ### 贡献流程
202
-
203
- ```
204
- ① clone wl-skills-kit 仓库 → 创建 feature 分支
205
- ② 修改 + 本地测试（npx . --dry-run）
206
- ③ 提 PR → Review → 合并
207
- ④ npm version → npm publish
208
- ⑤ 各项目 npx @jhlc/wl-skills-kit@latest
209
- ```
210
-
211
- ---
212
-
213
- ## 七、移植到新项目
214
-
215
- 详见 [use-skill.md](use-skill.md)「第四章：移植到新项目」。核心步骤：
216
-
217
- 1. `npx @jhlc/wl-skills-kit` → 导入全部文件
218
- 2. 执行 convention-extract Skill → 生成适配新项目的 copilot-instructions.md
219
- 3. 改写 page-codegen 代码模板（替换基类、组件、API 调用方式）
220
- 4. 验证：拿一个页面走完整 Skill 流程
221
-
222
- ### 依赖检查（⚠️ 必做）
223
-
224
- Skill 生成的代码依赖以下包，新项目需确认已安装：
225
-
226
- | 包名 | 类型 | 用途 | 安装命令 |
227
- | ------------------ | ------ | ----------------------- | ------------------------------ |
228
- | `mockjs` | devDep | Mock 数据生成 | `pnpm add -D mockjs` |
229
- | `vite-plugin-mock` | devDep | Vite 自动加载 mock/ | `pnpm add -D vite-plugin-mock` |
230
- | `lodash-es` | dep | debounce（RECORD_FORM） | `pnpm add lodash-es` |
231
- | `xlsx` | dep | 导出/导入按钮（按需） | `pnpm add xlsx` |
232
-
233
- > ⚠️ `lodash` ≠ `lodash-es`，两者不互通，模板代码 import 的是 `lodash-es`（ESM）。
234
-
235
- ---
236
-
237
- ## 八、版本管理
238
-
239
- ```
240
- MAJOR.MINOR.PATCH
241
- │ │ └── Skill bug fix / 文档修正
242
- │ └──────── 新增 Skill / 组件 / 领域样例 / 编辑器支持
243
- └────────────── 目录结构变更（breaking）
244
- ```
245
-
246
- ---
247
-
248
- ## 九、路线图
249
-
250
- | 阶段 | 内容 | 优先级 |
251
- | -------- | ----------------------------------------------------------------- | ------ |
252
- | **v1.0** | Skills + 文档 + 组件 + demo 样例（Copilot） | 🔴 高 |
253
- | **v1.1** | 多编辑器配置自动生成（Cursor / Windsurf / Kiro / Trae / Claude Code / AGENTS.md）| ✅ 已发布 |
254
- | **v1.2** | `--dry-run` 预览 + `--diff` 变更对比 | 🟡 中 |
255
- | **v2.0** | 纳入 `components/template/`（成熟后） | 🟢 低 |
256
-
257
- ---
258
-
259
- ## 附录：社区参考
260
-
261
- | 项目 | 说明 |
262
- | ------------- | ------------------------------- |
263
- | Ruler | 30+ AI agent 规则集中管理 |
264
- | rule-porter | Cursor ↔ AGENTS.md 双向转换 |
265
- | killer-skills | 社区 Skill 安装器 |
266
- | AGENTS.md | Linux Foundation 跨工具指令标准 |
1
+ # wl-skills-kit — AI Skill 模板包
2
+
3
+ > 统一维护、一键分发：AI 指令 + 组件文档 + 通用组件 + 领域样例。
4
+ > 安装即导入，无副作用，各项目通过 `npx @agile-team/wl-skills-kit` 同步更新。
5
+
6
+ ---
7
+
8
+ ## 一、定位
9
+
10
+ **wl-skills-kit** 是公司前端 AI 生态的基础设施包。
11
+
12
+ | 是什么 | 不是什么 |
13
+ | ---------------------------------------- | ----------------------------------- |
14
+ | 文件模板包，安装后按目录结构导入项目 | 不是运行时依赖 |
15
+ | AI 指令 + 文档 + 组件 + 样例的统一维护源 | 不修改 package.json / node_modules |
16
+ | 各项目同步更新的唯一通道 | 不执行 postinstall / 不删除任何文件 |
17
+
18
+ **一句话**：`npx @agile-team/wl-skills-kit` = 把模板文件复制到你的项目。完毕。
19
+
20
+ ---
21
+
22
+ ## 二、包目录结构
23
+
24
+ ```
25
+ @agile-team/wl-skills-kit/
26
+ ├── package.json ← name: "@agile-team/wl-skills-kit"
27
+ ├── README.md
28
+ ├── CHANGELOG.md
29
+ ├── bin/
30
+ │ └── wl-skills.js ← CLI 入口（文件拷贝 + 进度提示）
31
+ │
32
+ └── files/ ← 1:1 映射到目标项目根目录
33
+ │
34
+ ├── .github/ ← ① AI 指令（核心）
35
+ │ ├── copilot-instructions.md ← 项目规范总纲
36
+ │ ├── skills/
37
+ │ │ ├── prototype-scan/SKILL.md ← 原型扫描
38
+ │ │ ├── api-contract/SKILL.md ← 接口约定
39
+ │ │ ├── page-codegen/ ← 页面代码生成
40
+ │ │ │ ├── SKILL.md ← 主规则（~825 行）
41
+ │ │ │ └── TPL-*.md ← 9 个模板（LIST / FORM-ROUTE / MASTER-DETAIL /
42
+ │ │ │ TREE-LIST / DETAIL-TABS / CHANGE-HISTORY /
43
+ │ │ │ RECORD-FORM / OPERATION-STATION / DRIVEN）
44
+ │ │ ├── menu-sync/
45
+ │ │ │ ├── SKILL.md ← 菜单同步
46
+ │ │ │ └── env/guide.md ← env.local.json 配置说明（json 本身不分发）
47
+ │ │ └── convention-extract/SKILL.md ← 规范提炼
48
+ │ └── docs/
49
+ │ ├── use-skill.md ← 使用 + 移植一站式指南
50
+ │ ├── menu-sync-design.md ← 菜单同步方案设计
51
+ │ ├── SYS_MENU_INFO.md ← 菜单注册记录模板
52
+ │ └── wl-skills-kit.md ← 本文档
53
+ │
54
+ ├── docs/ ← ② 组件文档（12 个 md）
55
+ │ ├── request.md ← HTTP 请求工具
56
+ │ ├── page-query-hook-best-practices.md
57
+ │ ├── jh-select.md / jh-date.md / jh-date-range.md
58
+ │ ├── jh-drag-row.md / jh-pagination.md / jh-file-upload.md
59
+ │ └── jh-text.md / jh-user-picker.md / jh-dept-picker.md / jh-picker.md
60
+ │
61
+ ├── src/
62
+ │ ├── components/ ← ③ 通用组件
63
+ │ │ ├── global/ ← C_Splitter / C_Tree / C_TagStatus
64
+ │ │ │ C_ParentView / C_SvgIcon / C_RightToolbar
65
+ │ │ ├── local/ ← c_formModal / c_formSections
66
+ │ │ │ c_listModal / c_spliterTitle
67
+ │ │ └── remote/ ← BaseQuery / BaseTable / BaseToolbar
68
+ │ │ BaseForm / AGGrid（仅 README）
69
+ │ └── types/page.ts ← ④ 类型桶文件
70
+ │
71
+ └── demo/ ← ⑤ 领域样例（AI 学习 + 开发参考）
72
+ ├── README.md ← 样例索引 + 模板类型标注
73
+ ├── produce/
74
+ │ └── aiflow/ ← 生产域 8 个页面
75
+ │ ├── mmwr-customer-archive/ ← LIST + Tabs + c_formModal
76
+ │ ├── mmwr-temp-customer-archive/ ← LIST
77
+ │ ├── mmwr-customer-apply-add/ ← LIST
78
+ │ ├── mmwr-customer-apply-add-form/ ← FORM_ROUTE
79
+ │ ├── mmwr-customer-apply-change/ ← LIST
80
+ │ ├── mmwr-customer-apply-change-form/ ← FORM_ROUTE
81
+ │ ├── mmwr-customer-apply-change-history/ ← CHANGE_HISTORY
82
+ │ └── mmwr-customer-detail/ ← DETAIL_TABS
83
+ └── sale/
84
+ └── demo/ ← 销售域 5 个页面（平台默认样例）
85
+ ├── domestic-trade-order/ ← LIST 标准列表
86
+ ├── metallurgical-spec/ ← MASTER_DETAIL 上下分栏
87
+ ├── add-demo/ ← FORM_ROUTE（c_formSections）
88
+ ├── billet-flame-cut-plan/ ← LIST 变体
89
+ └── heat-batch-return/ ← LIST + 自定义弹窗
90
+ ```
91
+
92
+ > `files/` 下所有内容按原始路径写入项目根目录。**仅此而已，无其他逻辑。**
93
+
94
+ ### 不分发的内容
95
+
96
+ | 路径 | 原因 |
97
+ | ------------------------------------------- | ---------------------------------------- |
98
+ | `src/components/template/*` | 高阶封装，v2.0 稳定后再纳入 |
99
+ | `src/components/local/c_customerTabs/` | 客户域专用 |
100
+ | `src/components/local/c_applyDetailDialog/` | 客户域专用 |
101
+ | `src/components/local/c_actionModal/` | 客户域专用 |
102
+ | `menu-sync/env/env.local.json` | 含 Token，各项目本地维护（已 gitignore） |
103
+
104
+ ---
105
+
106
+ ## 三、使用方式
107
+
108
+ ```bash
109
+ # 安装 / 初始化（首次）
110
+ npx @agile-team/wl-skills-kit
111
+
112
+ # 同步更新（拉取最新模板）
113
+ npx @agile-team/wl-skills-kit@latest
114
+
115
+ # 预览变更（不写入，仅输出文件列表）
116
+ npx @agile-team/wl-skills-kit --dry-run
117
+ ```
118
+
119
+ | ✅ 做什么 | ❌ 不做什么 |
120
+ | ------------------------------ | -------------------- |
121
+ | 写入 .github/ docs/ src/ demo/ | 不修改 package.json |
122
+ | 覆盖同名文件 | 不修改 node_modules/ |
123
+ | 创建不存在的目录 | 不执行 postinstall |
124
+ | | 不删除任何文件 |
125
+
126
+ ### 安全路径（不会被覆盖）
127
+
128
+ 以下路径不在分发范围内，本地修改永远安全：
129
+
130
+ ```
131
+ .github/skills/my-domain-skill/ ← 自定义 Skill（非内置名）
132
+ .github/docs/my-domain-doc.md ← 自定义文档
133
+ src/components/local/my_custom/ ← 自定义组件
134
+ src/views/ ← 业务页面
135
+ mock/ ← Mock 数据
136
+ ```
137
+
138
+ | 修改类型 | 做法 |
139
+ | -------- | --------------------------------------------------- |
140
+ | 通用改进 | **提 PR 到 wl-skills-kit 仓库**，合并后所有项目受益 |
141
+ | 领域专有 | 放在上述安全路径，不会被覆盖 |
142
+
143
+ ---
144
+
145
+ ## 四、多编辑器支持
146
+
147
+ v1.0 聚焦 **GitHub Copilot**（`.github/` 目录即完整配置）。
148
+
149
+ v1.1 实现：CLI 安装时自动从 `.github/copilot-instructions.md` **动态生成**各编辑器配置文件。单一源头，更新 `copilot-instructions.md` 后重新运行即同步所有编辑器配置。
150
+
151
+ | 编辑器 | 配置路径 | 状态 |
152
+ | ------------------ | -------------------------------------------------------------- | ------- |
153
+ | **GitHub Copilot** | `.github/copilot-instructions.md` + `skills/` | ✅ v1.0 |
154
+ | **Cursor** | `.cursorrules` + `.cursor/rules/conventions.mdc` (alwaysApply) | ✅ v1.1 |
155
+ | **Windsurf** | `.windsurfrules` | ✅ v1.1 |
156
+ | **Kiro** | `.kiro/steering/conventions.md` | ✅ v1.1 |
157
+ | **Trae** | `.trae/rules/conventions.md` | ✅ v1.1 |
158
+ | **Claude Code** | `CLAUDE.md` | ✅ v1.1 |
159
+ | **Roo / Cline** | `.clinerules` | ✅ v1.1 |
160
+ | **AGENTS.md** | `AGENTS.md`（Linux Foundation 标准，通用兜底） | ✅ v1.1 |
161
+
162
+ > **原则**：AGENTS.md 是跨工具兜底标准，新工具出来大概率支持它。
163
+
164
+ ---
165
+
166
+ ## 五、发布策略
167
+
168
+ | 方式 | 场景 | 命令 |
169
+ | -------------------- | ----------- | ---------------------------------------------------- |
170
+ | **npm 公有**（优先） | 公开发布 | `npm publish --access public` |
171
+ | **私有 npm**（备选） | 内网团队 | `npm config set @agile-team:registry http://npm.nisco.cn/` |
172
+ | **Git 直装** | 无 npm 仓库 | `npx git+http://git.nisco.cn/PSQF/wl-skills-kit.git` |
173
+ | **离线 tgz** | 隔离网络 | `npm pack` → `npx ./jhlc-wl-skills-kit-x.x.x.tgz` |
174
+
175
+ ---
176
+
177
+ ## 六、贡献指南
178
+
179
+ ### 可贡献内容
180
+
181
+ | 类型 | 示例 | 贡献者 |
182
+ | ---------- | ----------------------------------- | -------------- |
183
+ | Skill 修复 | 修复 page-codegen 生成 bug | 任何使用者 |
184
+ | 组件文档 | 新增 jh-xxx 文档 | 平台组件开发者 |
185
+ | 领域样例 | `demo/{domain}/{submodule}/{page}/` | 各域开发者 |
186
+ | 通用组件 | 新增 c_xxxModal | 架构组 |
187
+
188
+ ### 样例贡献规范
189
+
190
+ 每个样例目录必须包含：
191
+
192
+ | 文件 | 必须 | 说明 |
193
+ | ------------ | ---- | ---------------------------------------- |
194
+ | `index.vue` | ✅ | 视图层 |
195
+ | `data.ts` | ✅ | 逻辑层（必须用 `createPage()` 标准模式） |
196
+ | `index.scss` | ✅ | 样式层 |
197
+ | `api.md` | 可选 | 有 API 约定时提供 |
198
+
199
+ **质量要求**：使用 Mock 数据（不依赖后端即可运行），脱敏处理（无真实手机号、客户名等）。
200
+
201
+ ### 贡献流程
202
+
203
+ ```
204
+ ① clone wl-skills-kit 仓库 → 创建 feature 分支
205
+ ② 修改 + 本地测试（npx . --dry-run）
206
+ ③ 提 PR → Review → 合并
207
+ ④ npm version → npm publish
208
+ ⑤ 各项目 npx @agile-team/wl-skills-kit@latest
209
+ ```
210
+
211
+ ---
212
+
213
+ ## 七、移植到新项目
214
+
215
+ 详见 [use-skill.md](use-skill.md)「第四章：移植到新项目」。核心步骤：
216
+
217
+ 1. `npx @agile-team/wl-skills-kit` → 导入全部文件
218
+ 2. 执行 convention-extract Skill → 生成适配新项目的 copilot-instructions.md
219
+ 3. 改写 page-codegen 代码模板（替换基类、组件、API 调用方式）
220
+ 4. 验证：拿一个页面走完整 Skill 流程
221
+
222
+ ### 依赖检查（⚠️ 必做）
223
+
224
+ Skill 生成的代码依赖以下包，新项目需确认已安装：
225
+
226
+ | 包名 | 类型 | 用途 | 安装命令 |
227
+ | ------------------ | ------ | ----------------------- | ------------------------------ |
228
+ | `mockjs` | devDep | Mock 数据生成 | `pnpm add -D mockjs` |
229
+ | `vite-plugin-mock` | devDep | Vite 自动加载 mock/ | `pnpm add -D vite-plugin-mock` |
230
+ | `lodash-es` | dep | debounce（RECORD_FORM） | `pnpm add lodash-es` |
231
+ | `xlsx` | dep | 导出/导入按钮（按需） | `pnpm add xlsx` |
232
+
233
+ > ⚠️ `lodash` ≠ `lodash-es`，两者不互通，模板代码 import 的是 `lodash-es`（ESM）。
234
+
235
+ ---
236
+
237
+ ## 八、版本管理
238
+
239
+ ```
240
+ MAJOR.MINOR.PATCH
241
+ │ │ └── Skill bug fix / 文档修正
242
+ │ └──────── 新增 Skill / 组件 / 领域样例 / 编辑器支持
243
+ └────────────── 目录结构变更（breaking）
244
+ ```
245
+
246
+ ---
247
+
248
+ ## 九、路线图
249
+
250
+ | 阶段 | 内容 | 优先级 |
251
+ | -------- | ----------------------------------------------------------------- | ------ |
252
+ | **v1.0** | Skills + 文档 + 组件 + demo 样例（Copilot） | 🔴 高 |
253
+ | **v1.1** | 多编辑器配置自动生成（Cursor / Windsurf / Kiro / Trae / Claude Code / AGENTS.md）| ✅ 已发布 |
254
+ | **v1.2** | `--dry-run` 预览 + `--diff` 变更对比 | 🟡 中 |
255
+ | **v2.0** | 纳入 `components/template/`（成熟后） | 🟢 低 |
256
+
257
+ ---
258
+
259
+ ## 附录：社区参考
260
+
261
+ | 项目 | 说明 |
262
+ | ------------- | ------------------------------- |
263
+ | Ruler | 30+ AI agent 规则集中管理 |
264
+ | rule-porter | Cursor ↔ AGENTS.md 双向转换 |
265
+ | killer-skills | 社区 Skill 安装器 |
266
+ | AGENTS.md | Linux Foundation 跨工具指令标准 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agile-team/wl-skills-kit",
3
- "version": "1.1.0",
3
+ "version": "1.1.2",
4
4
  "description": "AI Skill 模板包 — 一键导入 AI 指令 + 组件文档 + 通用组件 + 领域样例，覆盖 Copilot/Cursor/Windsurf/Kiro 等主流 AI 编辑器",
5
5
  "bin": {
6
6
  "wl-skills-kit": "./bin/wl-skills.js"
@@ -24,7 +24,7 @@
24
24
  "agents"
25
25
  ],
26
26
  "author": "JHLC Frontend Team",
27
- "license": "MIT",
27
+ "license": "UNLICENSED",
28
28
  "repository": {
29
29
  "type": "git",
30
30
  "url": "git+https://github.com/ChenyCHENYU/wl-skills-kit.git"