@agile-team/wl-skills-kit 2.3.2 → 2.3.3

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 (3) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +138 -9
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.3.3] - 2026-04-28
4
+
5
+ ### 📝 README 大幅重写 + Skill 状态校正
6
+
7
+ #### README 新增核心章节
8
+ - **文档地图 & 架构导读**：按角色（设计师/业务分析师/后端/前端/维护者）列出各自入口；各目录职责一览；“读哪个 README”导航表
9
+ - **设计理念**：三层分工结构（SKILL.md 语义层 / MCP tools 执行层 / HTTP API 数据层）
10
+ - **当前能力全景**：完整的从输入到输出的流程图，包括 MCP 工具层在链路中的位置
11
+ - **Roadmap**：按优先级列出 permission-sync 等待做事项
12
+ - **未来设想**：完整自动化链路展望
13
+
14
+ #### Skill 状态校正
15
+ - `dict-sync`：已有完整 SKILL.md，从 ⏳ PLANNED 改为 ✅ 启用
16
+ - `code-fix`：已有完整 SKILL.md，从 ⏳ PLANNED 改为 ✅ 启用
17
+ - `permission-sync`：仍是 SKILL.draft.md，保持 ⏳ PLANNED
18
+ - Skills 总数更新：6 → 8 个已启用，1 个 PLANNED（两处描述同步更新）
19
+
20
+ ---
21
+
3
22
  ## [2.3.2] - 2026-04-28
4
23
 
5
24
  ### 📝 输入规范文档体系 + README/目录结构优化
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @agile-team/wl-skills-kit
2
2
 
3
- **AI Skill 模板包 v2.3** — 一条命令将 13 条编码规范、6 个 AI Skill、组件文档、领域样例导入 Vue 3 项目。
3
+ **AI Skill 模板包 v2.3** — 一条命令将 13 条编码规范、8 个 AI Skill、MCP 工具层、组件文档、领域样例导入 Vue 3 项目。
4
4
 
5
5
  让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
6
6
 
@@ -41,6 +41,135 @@ reports/AUDIT_AI_*.md + AUDIT_HUMAN_*.md
41
41
 
42
42
  ---
43
43
 
44
+ ## 文档地图 — 谁该读什么
45
+
46
+ > 这个项目覆盖了多个角色和多层目录，先花 30 秒定位自己，再按需深入。
47
+
48
+ ### 按角色找入口
49
+
50
+ | 你的身份 | 你要做的事 | 从这里开始 |
51
+ |---|---|---|
52
+ | **业务团队（首次接入）** | 安装、跑通 AI 代码生成流程 | 本文档 → CLI 命令 → 业务项目内 `.github/guides/usage.md` |
53
+ | **设计师 / 产品经理** | 了解如何制作让 AI 精确识别的原型 | [docs/input-spec-prototype.md](docs/input-spec-prototype.md) |
54
+ | **业务分析师** | 了解详设文档需要提供哪些结构化内容 | [docs/input-spec-detailed-design.md](docs/input-spec-detailed-design.md) |
55
+ | **后端开发者** | 了解接口命名/响应格式规范，如何确认 api.md | [docs/input-spec-api.md](docs/input-spec-api.md) |
56
+ | **前端开发者** | 理解 page-spec JSON 结构，手写或校验 | [docs/input-spec-page-spec.md](docs/input-spec-page-spec.md) |
57
+ | **wl-skills-kit 维护者** | 修改规范、Skill、模板、CLI | [kit-internal/README.md](kit-internal/README.md) |
58
+
59
+ ### 各目录职责一览
60
+
61
+ ```
62
+ wl-skills-kit/
63
+ │
64
+ ├── files/ ← ★ 打包分发给业务项目的全部内容
65
+ │ ├── .github/ AI 指令体系（规范+Skill+适配层+报告模板）
66
+ │ ├── docs/ 随包分发的组件 API 文档（12 个组件）
67
+ │ └── demo/ 领域样例代码（供 AI 参考学习）
68
+ │
69
+ ├── mcp/ ← ★ MCP Server（随包分发，Cursor 自动注册）
70
+ │ 4 个工具：菜单查询/写入 + 字典查询/写入
71
+ │
72
+ ├── bin/ ← CLI 实现（init / update / clean）
73
+ │
74
+ ├── docs/ ← 仅本仓库可见（不分发）
75
+ │ 输入规范文档系列（面向团队各角色）
76
+ │
77
+ └── kit-internal/ ← 仅本仓库可见（不分发）
78
+ 维护者文档（架构 ADR、贡献流程、踩坑记录）
79
+ ```
80
+
81
+ ### 读哪个 README
82
+
83
+ | README 文件 | 内容 | 读者 |
84
+ |---|---|---|
85
+ | 本文件（根 README.md） | 包概述、安装使用、Skill 全景 | 所有人 |
86
+ | `kit-internal/README.md` | 维护者工作空间总览 | 维护者 |
87
+ | `files/.github/guides/usage.md` | 业务项目安装后的完整使用流程 | 业务团队 |
88
+ | `files/.github/guides/architecture.md` | AI 体系架构与设计决策 | 想深入了解的技术同学 |
89
+ | `files/.github/skills/*/USAGE.md` | 每个 Skill 的触发方式和效果说明 | 业务团队按需查阅 |
90
+ | `docs/input-spec-*.md` | 各角色的输入规范最佳实践 | 设计/分析/后端/前端 |
91
+
92
+ ---
93
+
94
+ ## 设计理念 & 演进路线
95
+
96
+ ### 核心设计理念
97
+
98
+ **"一次写好 Skill，人人获益"** — wl-skills-kit 不是项目脚手架，而是一套 **AI 行为规范体系**。
99
+
100
+ 通过将团队的编码规范、业务模式、设计决策编码到 SKILL.md 中，让每一个 AI 编辑器在每一次对话里都能遵守相同的规范——无论是 Copilot、Cursor 还是 Claude Code，无论是老成员还是新同学，AI 的行为都是可预期的、一致的。
101
+
102
+ **三层分工**：
103
+
104
+ ```
105
+ SKILL.md（语义层） AI 编辑器理解"该怎么做"
106
+ │
107
+ ▼
108
+ MCP tools / CLI（执行层） 跨越 AI 上下文边界，调用真实系统
109
+ │
110
+ ▼
111
+ mcp/api/ / 后端 HTTP API 实际的数据读写
112
+ ```
113
+
114
+ - **SKILL.md** — 静态知识，放在 AI 编辑器的上下文里，零运行时开销
115
+ - **MCP 工具** — 当 Skill 需要读写真实系统（菜单树/字典表）时，通过 MCP 调用，跨越 AI 上下文边界
116
+ - **纯查询/生成类 Skill**（如 page-codegen / convention-audit）不需要 MCP，SKILL.md 直接驱动
117
+
118
+ ### 当前能力全景（v2.3）
119
+
120
+ ```
121
+ 输入层 AI 推理层 输出层
122
+ ───────── ───────────────────── ─────────────────
123
+ Axure HTML 原型 → prototype-scan → page-spec JSON
124
+ 详设 Markdown 表 → prototype-scan → page-spec JSON
125
+ 口述需求 → prototype-scan (推断) → page-spec JSON
126
+ │
127
+ ▼
128
+ api-contract → api.md（逐页面）
129
+ │
130
+ ▼
131
+ page-codegen → data.ts + index.vue
132
+ （8 种内置模板） + index.scss + pages.ts
133
+ │
134
+ ▼
135
+ convention-audit → AUDIT_AI.md（AI 自查）
136
+ AUDIT_HUMAN.md（人工检查）
137
+ │
138
+ ▼
139
+ code-fix → 受控自动整改偏差
140
+ │
141
+ ▼
142
+ menu-sync (MCP) → 线上菜单注册完毕
143
+ dict-sync (MCP) → 线上字典同步完毕
144
+ │
145
+ ▼
146
+ template-extract → 领域模板沉淀复用
147
+ ```
148
+
149
+ ### 下一步计划（Roadmap）
150
+
151
+ | 优先级 | 功能 | 状态 |
152
+ |---|---|---|
153
+ | 🔴 高 | `permission-sync` — 页面级/按钮级权限批量注册 | ⏳ SKILL.draft.md 已有设计 |
154
+ | 🟡 中 | `domain/` 领域模板扩展 — 补充 sale / hrms 等领域样例 | ⏳ 规划中 |
155
+ | 🟡 中 | `page-codegen` 支持更多 Template 组件（cx-ui-produce 的配置驱动页面）| ⏳ 持续补充 |
156
+ | 🟢 低 | MCP 增加 permission 工具（`wls_permission_query/upsert`）| ⏳ 依赖 permission-sync Skill |
157
+ | 🟢 低 | `code-fix` 完善 — 覆盖更多自动修复场景 | ⏳ 持续完善 |
158
+
159
+ ### 未来设想
160
+
161
+ 当 permission-sync 完成后，一个新页面从 0 到线上可访问的完整链路将全自动化：
162
+
163
+ ```
164
+ 原型 → AI 生成代码 → convention-audit 验收 → menu-sync 注册菜单
165
+ → dict-sync 同步字典
166
+ → permission-sync 注册权限
167
+ ↓
168
+ UI 可访问，权限可分配
169
+ ```
170
+
171
+ ---
172
+
44
173
  ## ⚠️ 仓库结构 vs 业务项目安装结构（**必看**）
45
174
 
46
175
  `wl-skills-kit` 是一个 **npm 模板包**：仓库本身的结构 ≠ 你 `npx` 之后业务项目里看到的结构。两者**严格区分**：
@@ -104,7 +233,7 @@ wl-skills-kit/ ← 你正看的这个仓库
104
233
  │ │ ├── 02-code-structure.md
105
234
  │ │ ├── ... (共 13 条)
106
235
  │ │ └── 13-platform-components.md
107
- │ ├── skills/ 6 个启用 Skill + 3 个 PLANNED 草稿
236
+ │ ├── skills/ 8 个启用 Skill + 1 个 PLANNED 草稿
108
237
  │ │ ├── _registry.md ★ 触发词 → SKILL 路径单一数据源
109
238
  │ │ ├── _compat/ 多 AI 编辑器适配（配置 + headers）
110
239
  │ │ ├── core/ 核心通用 Skill
@@ -115,10 +244,10 @@ wl-skills-kit/ ← 你正看的这个仓库
115
244
  │ │ │ └── template-extract/ { SKILL.md, USAGE.md }
116
245
  │ │ ├── sync/ 数据同步类
117
246
  │ │ │ ├── menu-sync/ { SKILL.md, USAGE.md, env/ }
118
- │ │ │ ├── dict-sync/ [PLANNED] SKILL.draft.md
119
- │ │ │ └── permission-sync/ [PLANNED] SKILL.draft.md
247
+ │ │ │ ├── dict-sync/ { SKILL.md } 已启用
248
+ │ │ │ └── permission-sync/ [PLANNED] SKILL.draft.md 设计中
120
249
  │ │ ├── ops/ 运维类
121
- │ │ │ └── code-fix/ [PLANNED] SKILL.draft.md
250
+ │ │ │ └── code-fix/ { SKILL.md } 已启用
122
251
  │ │ └── domain/ 领域专属（按需创建）
123
252
  │ ├── guides/ 人读指南（usage.md / architecture.md）
124
253
  │ └── reports/ AI 生成报告（追加不覆盖）
@@ -201,10 +330,10 @@ npx @agile-team/wl-skills-kit update
201
330
  | `page-codegen` | ✅ 启用 | `skills/core/page-codegen/` | 4 文件骨架生成 + 模板调度 |
202
331
  | `convention-audit` | ✅ 启用 | `skills/core/convention-audit/` | 13 条规范扫描 + 双报告 |
203
332
  | `template-extract` | ✅ 启用 | `skills/core/template-extract/` | 现有页面 → 领域模板 |
204
- | `menu-sync` | ✅ 启用 | `skills/sync/menu-sync/` | 菜单基线 ↔ 后端接口 |
205
- | `dict-sync` | ⏳ PLANNED | `skills/sync/dict-sync/` | 字典基线 ↔ 后端接口 |
206
- | `permission-sync` | ⏳ PLANNED | `skills/sync/permission-sync/` | 权限基线 ↔ 后端接口 |
207
- | `code-fix` | ⏳ PLANNED | `skills/ops/code-fix/` | 受控自动修复偏差 |
333
+ | `menu-sync` | ✅ 启用 | `skills/sync/menu-sync/` | 菜单基线 ↔ 后端接口（MCP） |
334
+ | `dict-sync` | ✅ 启用 | `skills/sync/dict-sync/` | 字典基线 ↔ 后端接口（MCP） |
335
+ | `code-fix` | ✅ 启用 | `skills/ops/code-fix/` | 受控自动修复偏差 |
336
+ | `permission-sync` | ⏳ PLANNED | `skills/sync/permission-sync/` | 权限基线 ↔ 后端接口（设计中） |
208
337
 
209
338
  每个启用 Skill 同目录都有 **`SKILL.md`（AI 触发用）+ `USAGE.md`（团队成员阅读）**。
210
339
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agile-team/wl-skills-kit",
3
- "version": "2.3.2",
3
+ "version": "2.3.3",
4
4
  "description": "AI Skill 模板包 — 一键导入 AI 指令 + 组件文档 + 通用组件 + 领域样例，覆盖 Copilot/Cursor/Windsurf/Kiro 等主流 AI 编辑器",
5
5
  "main": "./bin/wl-skills.js",
6
6
  "bin": {