@agile-team/wl-skills-kit 2.7.2 → 2.8.0
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.
- package/CHANGELOG.md +37 -0
- package/README.md +40 -12
- package/bin/wl-skills.js +147 -3
- package/files/.github/copilot-instructions.md +18 -0
- package/files/.github/guides/architecture.md +6 -4
- package/files/.github/skills/_best-practices.md +230 -220
- package/files/.github/skills/core/page-codegen/SKILL.md +5 -5
- package/files/.github/skills/sync/_mcp-guardrail.md +109 -109
- package/files/.github/skills/sync/dict-sync/SKILL.md +208 -208
- package/files/.github/skills/sync/permission-sync/SKILL.md +240 -275
- package/files/docs/mock-architecture.md +321 -0
- package/files/mock/_utils.ts +35 -0
- package/mcp/api/client.js +83 -83
- package/mcp/tools/dictSync.js +178 -173
- package/mcp/tools/menuSync.js +11 -0
- package/package.json +2 -2
|
@@ -1,109 +1,109 @@
|
|
|
1
|
-
# Sync Skill 通用护栏（MCP 调用纪律 + 自愈闭环）
|
|
2
|
-
|
|
3
|
-
> 所有 sync 类 Skill（menu-sync / dict-sync / permission-sync）共用本规则。
|
|
4
|
-
> SKILL.md 顶部需引用本文件，确保 AI 行为一致。
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## 1. 调用纪律（AI 必读）
|
|
9
|
-
|
|
10
|
-
- ✅ **首选**：通过本 Skill 在「MCP 工具调用规范」中列出的工具调用（`wls_*`）
|
|
11
|
-
- ❌ **严禁**：使用 `curl` / `Invoke-RestMethod` / `Invoke-WebRequest` / `fetch` / `axios` / `Send-WebRequest` 等任何 shell 命令或代码直接发起 HTTP 请求
|
|
12
|
-
- ❌ **严禁**：自行推测、拼接、或从历史对话沿用接口路径
|
|
13
|
-
- ❌ **严禁**：在 SKILL.md 中看到 `POST /system/xxx/save` 字样后据此手动调用——HTTP 路径仅为 MCP **内部实现说明**
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## 2. 自愈闭环（MCP 异常时 AI 该怎么做）
|
|
18
|
-
|
|
19
|
-
> 不是"立即停止"，而是"按层级引导用户完善配置，让它能跑通"。原则：**优先帮用户闭环，最后才放弃**。
|
|
20
|
-
|
|
21
|
-
### 2.1 错误分层判定
|
|
22
|
-
|
|
23
|
-
AI 调用 MCP 工具后，按返回内容判定属于哪一类，并按对应剧本处理：
|
|
24
|
-
|
|
25
|
-
| 错误特征 | 归类 | 处理剧本 |
|
|
26
|
-
|---|---|---|
|
|
27
|
-
| 工具不在 `tools/list` 中（编辑器根本没识别到 wls_*）| L0 MCP 未连接 | 走 §2.2 |
|
|
28
|
-
| 工具返回"❌ 配置加载失败"/"配置文件不存在"/"请填写真实的 xxx" | L1 配置缺失 | 走 §2.3 |
|
|
29
|
-
| 工具返回 `code === 401` 或包含 "token"/"鉴权"/"未登录" 字样 | L2 Token 失效 | 走 §2.4 |
|
|
30
|
-
| 工具返回 `code === 4004` / "url:GET; ..." / 接口不存在 | L3 接口路径不匹配 | 走 §2.5 |
|
|
31
|
-
| 工具返回业务错误（参数错误、唯一键冲突等） | L4 业务层 | 按工具返回的提示给用户看，不需要 fallback |
|
|
32
|
-
|
|
33
|
-
### 2.2 L0 — MCP 未连接
|
|
34
|
-
|
|
35
|
-
引导（不要默认放弃）：
|
|
36
|
-
|
|
37
|
-
```
|
|
38
|
-
🔧 当前编辑器似乎未识别到 wls_* 工具，请按顺序检查：
|
|
39
|
-
1. 编辑器的 MCP 配置文件存在吗？（Cursor/Kiro/Trae: 见各自 mcp.json）
|
|
40
|
-
2. 配置里 WL_PROJECT_ROOT 指向当前项目根了吗？
|
|
41
|
-
3. 重启编辑器后再看 MCP 面板的工具列表
|
|
42
|
-
|
|
43
|
-
请告诉我以上哪一步通不过，我帮你定位。
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
仅在用户明确表示**无法启用 MCP** 时，才退化为「手工去后台维护」的人肉方案，且**不再尝试**让 AI 拼 HTTP。
|
|
47
|
-
|
|
48
|
-
### 2.3 L1 — 配置缺失 / 占位值未替换
|
|
49
|
-
|
|
50
|
-
如果工具返回类似：
|
|
51
|
-
- `请在 env.local.json 中填写真实的 gatewayPath（当前为占位值）`
|
|
52
|
-
- `请在 .github/skills/sync/env.local.json 填写 menu.domainId`
|
|
53
|
-
- `配置文件不存在: .../env.local.json`
|
|
54
|
-
|
|
55
|
-
AI **立即转入引导模式**：
|
|
56
|
-
|
|
57
|
-
1. `read_file` 加载 `.github/skills/sync/menu-sync/env/guide.md`（统一配置说明）
|
|
58
|
-
2. 告诉用户具体哪个字段缺失、获取方式（如 token 抓包、domainId Network 查询）
|
|
59
|
-
3. 等待用户填好 `env.local.json` 后**自动重试同一个 MCP 工具调用**
|
|
60
|
-
4. 直到配置完整、调用成功为止 → 完成闭环
|
|
61
|
-
|
|
62
|
-
### 2.4 L2 — Token 失效
|
|
63
|
-
|
|
64
|
-
```
|
|
65
|
-
🔑 Token 似乎已过期。请：
|
|
66
|
-
1. 浏览器登录系统
|
|
67
|
-
2. F12 → Network → 任意接口 → 复制 authorization 头的值
|
|
68
|
-
3. 去掉开头的 `bearer ` 前缀，把纯 JWT 部分粘到 env.local.json 的 token 字段
|
|
69
|
-
4. 告诉我"token 已更新"，我会重新尝试同步
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
更新后**自动重跑**之前失败的 MCP 调用。
|
|
73
|
-
|
|
74
|
-
### 2.5 L3 — 接口路径不匹配（如 4004）
|
|
75
|
-
|
|
76
|
-
后端环境差异可能导致内置接口路径与实际不符。AI 应：
|
|
77
|
-
|
|
78
|
-
1. 提示用户："当前 MCP 内置的接口路径在你的后端未注册（返回 4004）。可能是该环境网关前缀不同。"
|
|
79
|
-
2. 引导用户：
|
|
80
|
-
- 检查 `env.local.json.gatewayPath` 是否需要补一段前缀（如 `/uac`）
|
|
81
|
-
- 或者联系后端确认该 sync 工具对应的真实路径
|
|
82
|
-
3. **不要**让 AI 自行去猜路径再 curl，否则就是绕开 MCP 的回旋
|
|
83
|
-
4. 路径前缀这类配置类问题可以由用户更新后**重试 MCP 工具**完成闭环
|
|
84
|
-
|
|
85
|
-
> 长期方案：将变化的接口前缀做成 `env.local.json` 中的可配置项，由 kit 维护者在 mcp/api/*.js 中支持读取覆盖。该改动属于 MCP 内部实现，AI 不需要也不应该自行 patch。
|
|
86
|
-
|
|
87
|
-
### 2.6 L4 — 业务错误
|
|
88
|
-
|
|
89
|
-
工具返回的业务层提示（如 "menuName 已存在"、"参数缺失"）属正常反馈，AI 直接展示给用户即可，不需要 fallback。
|
|
90
|
-
|
|
91
|
-
---
|
|
92
|
-
|
|
93
|
-
## 3. Pre-flight 自检模板（执行前必须输出）
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
🚀 已触发技能 {skill-name}/SKILL.md → {一句话用途}
|
|
97
|
-
✅ MCP 工具检查：{要用到的 wls_* 全部列出，✓/✗}
|
|
98
|
-
✅ 已读取 .github/skills/sync/env.local.json → gatewayPath/token/sysAppNo/{其他必填}
|
|
99
|
-
✅ 已读取 {本 Skill 的 SYS_*_INFO.md 基线}
|
|
100
|
-
✅ 操作模式：{pull / push / audit / ...}
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
任一项 ✗ → 进入 §2 自愈剧本，**不要直接放弃**。
|
|
104
|
-
|
|
105
|
-
---
|
|
106
|
-
|
|
107
|
-
## 4. 一句话总则
|
|
108
|
-
|
|
109
|
-
> **MCP 是默认通路，配置是参数化的；调不通时帮用户改配置，而不是绕开 MCP 自己拼 HTTP。**
|
|
1
|
+
# Sync Skill 通用护栏（MCP 调用纪律 + 自愈闭环）
|
|
2
|
+
|
|
3
|
+
> 所有 sync 类 Skill（menu-sync / dict-sync / permission-sync）共用本规则。
|
|
4
|
+
> SKILL.md 顶部需引用本文件，确保 AI 行为一致。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 1. 调用纪律（AI 必读）
|
|
9
|
+
|
|
10
|
+
- ✅ **首选**：通过本 Skill 在「MCP 工具调用规范」中列出的工具调用（`wls_*`）
|
|
11
|
+
- ❌ **严禁**：使用 `curl` / `Invoke-RestMethod` / `Invoke-WebRequest` / `fetch` / `axios` / `Send-WebRequest` 等任何 shell 命令或代码直接发起 HTTP 请求
|
|
12
|
+
- ❌ **严禁**：自行推测、拼接、或从历史对话沿用接口路径
|
|
13
|
+
- ❌ **严禁**：在 SKILL.md 中看到 `POST /system/xxx/save` 字样后据此手动调用——HTTP 路径仅为 MCP **内部实现说明**
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 2. 自愈闭环（MCP 异常时 AI 该怎么做）
|
|
18
|
+
|
|
19
|
+
> 不是"立即停止"，而是"按层级引导用户完善配置，让它能跑通"。原则：**优先帮用户闭环，最后才放弃**。
|
|
20
|
+
|
|
21
|
+
### 2.1 错误分层判定
|
|
22
|
+
|
|
23
|
+
AI 调用 MCP 工具后，按返回内容判定属于哪一类，并按对应剧本处理：
|
|
24
|
+
|
|
25
|
+
| 错误特征 | 归类 | 处理剧本 |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| 工具不在 `tools/list` 中（编辑器根本没识别到 wls_*）| L0 MCP 未连接 | 走 §2.2 |
|
|
28
|
+
| 工具返回"❌ 配置加载失败"/"配置文件不存在"/"请填写真实的 xxx" | L1 配置缺失 | 走 §2.3 |
|
|
29
|
+
| 工具返回 `code === 401` 或包含 "token"/"鉴权"/"未登录" 字样 | L2 Token 失效 | 走 §2.4 |
|
|
30
|
+
| 工具返回 `code === 4004` / "url:GET; ..." / 接口不存在 | L3 接口路径不匹配 | 走 §2.5 |
|
|
31
|
+
| 工具返回业务错误（参数错误、唯一键冲突等） | L4 业务层 | 按工具返回的提示给用户看，不需要 fallback |
|
|
32
|
+
|
|
33
|
+
### 2.2 L0 — MCP 未连接
|
|
34
|
+
|
|
35
|
+
引导（不要默认放弃）：
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
🔧 当前编辑器似乎未识别到 wls_* 工具，请按顺序检查：
|
|
39
|
+
1. 编辑器的 MCP 配置文件存在吗？（Cursor/Kiro/Trae: 见各自 mcp.json）
|
|
40
|
+
2. 配置里 WL_PROJECT_ROOT 指向当前项目根了吗？
|
|
41
|
+
3. 重启编辑器后再看 MCP 面板的工具列表
|
|
42
|
+
|
|
43
|
+
请告诉我以上哪一步通不过，我帮你定位。
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
仅在用户明确表示**无法启用 MCP** 时，才退化为「手工去后台维护」的人肉方案，且**不再尝试**让 AI 拼 HTTP。
|
|
47
|
+
|
|
48
|
+
### 2.3 L1 — 配置缺失 / 占位值未替换
|
|
49
|
+
|
|
50
|
+
如果工具返回类似：
|
|
51
|
+
- `请在 env.local.json 中填写真实的 gatewayPath（当前为占位值）`
|
|
52
|
+
- `请在 .github/skills/sync/env.local.json 填写 menu.domainId`
|
|
53
|
+
- `配置文件不存在: .../env.local.json`
|
|
54
|
+
|
|
55
|
+
AI **立即转入引导模式**：
|
|
56
|
+
|
|
57
|
+
1. `read_file` 加载 `.github/skills/sync/menu-sync/env/guide.md`（统一配置说明）
|
|
58
|
+
2. 告诉用户具体哪个字段缺失、获取方式（如 token 抓包、domainId Network 查询）
|
|
59
|
+
3. 等待用户填好 `env.local.json` 后**自动重试同一个 MCP 工具调用**
|
|
60
|
+
4. 直到配置完整、调用成功为止 → 完成闭环
|
|
61
|
+
|
|
62
|
+
### 2.4 L2 — Token 失效
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
🔑 Token 似乎已过期。请：
|
|
66
|
+
1. 浏览器登录系统
|
|
67
|
+
2. F12 → Network → 任意接口 → 复制 authorization 头的值
|
|
68
|
+
3. 去掉开头的 `bearer ` 前缀，把纯 JWT 部分粘到 env.local.json 的 token 字段
|
|
69
|
+
4. 告诉我"token 已更新"，我会重新尝试同步
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
更新后**自动重跑**之前失败的 MCP 调用。
|
|
73
|
+
|
|
74
|
+
### 2.5 L3 — 接口路径不匹配（如 4004）
|
|
75
|
+
|
|
76
|
+
后端环境差异可能导致内置接口路径与实际不符。AI 应：
|
|
77
|
+
|
|
78
|
+
1. 提示用户："当前 MCP 内置的接口路径在你的后端未注册（返回 4004）。可能是该环境网关前缀不同。"
|
|
79
|
+
2. 引导用户：
|
|
80
|
+
- 检查 `env.local.json.gatewayPath` 是否需要补一段前缀（如 `/uac`）
|
|
81
|
+
- 或者联系后端确认该 sync 工具对应的真实路径
|
|
82
|
+
3. **不要**让 AI 自行去猜路径再 curl，否则就是绕开 MCP 的回旋
|
|
83
|
+
4. 路径前缀这类配置类问题可以由用户更新后**重试 MCP 工具**完成闭环
|
|
84
|
+
|
|
85
|
+
> 长期方案：将变化的接口前缀做成 `env.local.json` 中的可配置项，由 kit 维护者在 mcp/api/*.js 中支持读取覆盖。该改动属于 MCP 内部实现，AI 不需要也不应该自行 patch。
|
|
86
|
+
|
|
87
|
+
### 2.6 L4 — 业务错误
|
|
88
|
+
|
|
89
|
+
工具返回的业务层提示（如 "menuName 已存在"、"参数缺失"）属正常反馈，AI 直接展示给用户即可，不需要 fallback。
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 3. Pre-flight 自检模板（执行前必须输出）
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
🚀 已触发技能 {skill-name}/SKILL.md → {一句话用途}
|
|
97
|
+
✅ MCP 工具检查：{要用到的 wls_* 全部列出，✓/✗}
|
|
98
|
+
✅ 已读取 .github/skills/sync/env.local.json → gatewayPath/token/sysAppNo/{其他必填}
|
|
99
|
+
✅ 已读取 {本 Skill 的 SYS_*_INFO.md 基线}
|
|
100
|
+
✅ 操作模式：{pull / push / audit / ...}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
任一项 ✗ → 进入 §2 自愈剧本，**不要直接放弃**。
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 4. 一句话总则
|
|
108
|
+
|
|
109
|
+
> **MCP 是默认通路，配置是参数化的；调不通时帮用户改配置，而不是绕开 MCP 自己拼 HTTP。**
|
|
@@ -1,208 +1,208 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: dict-sync
|
|
3
|
-
description: "Use when: syncing data dictionary entries to the backend, pulling the current online dictionary baseline, or checking which dictionaries used in data.ts are missing from the system. Triggers on: 同步字典, 创建字典, 刷新字典基线, 字典对比, 字典审计, dict sync, create dict."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Skill: 字典同步（dict-sync）
|
|
7
|
-
|
|
8
|
-
将 `data.ts` 中引用的数据字典（`logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"`）同步到后端字典表，保持本地基线与线上一致。
|
|
9
|
-
|
|
10
|
-
> **与 menu-sync / permission-sync 对称**：同样读取本地基线 → 与线上对比 → 补齐差异。配置共用 `skills/sync/env.local.json`。
|
|
11
|
-
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
## 📖 必读公共护栏
|
|
15
|
-
|
|
16
|
-
本 Skill 遵守 `../_mcp-guardrail.md`（MCP 调用纪律与自愈闭环）。AI 首次执行 sync 类任务时先 `read_file` 加载它。
|
|
17
|
-
|
|
18
|
-
本 Skill 使用的 MCP 工具：`wls_dict_query` / `wls_dict_upsert`。调用失败时按 guardrail §2 剧本引导用户完善 `env.local.json` 后重试，**不得用 curl/手拼 HTTP 绕开 MCP**。
|
|
19
|
-
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
## 配置（统一配置文件）
|
|
23
|
-
|
|
24
|
-
读取 `.github/skills/sync/env.local.json`（已在 `.gitignore`，不入 git）：
|
|
25
|
-
|
|
26
|
-
```json
|
|
27
|
-
{
|
|
28
|
-
"gatewayPath": "http://192.168.10.50:9000",
|
|
29
|
-
"sysAppNo": "QjQuXy1kbKxZyjhS5N2",
|
|
30
|
-
"token": "eyJhbGci...",
|
|
31
|
-
"dict": {
|
|
32
|
-
"moduleId": "7C909G0U2F8HI7E305LV0135LSJ3UBIO"
|
|
33
|
-
}
|
|
34
|
-
}
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
| 字段 | 说明 |
|
|
38
|
-
|---|---|
|
|
39
|
-
| `gatewayPath` | 后端网关，末尾不加斜杠 |
|
|
40
|
-
| `sysAppNo` | 应用编码（非明文） |
|
|
41
|
-
| `token` | 纯 JWT，**不含 `bearer ` 前缀**（MCP 内部自动拼接） |
|
|
42
|
-
| `dict.moduleId` | 字典所属模块 ID（字典管理后台 Network 抓取） |
|
|
43
|
-
|
|
44
|
-
> 字段获取方式见同目录 `../menu-sync/env/guide.md`。
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## Pre-flight 声明（执行前必须输出）
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
🚀 已触发技能 dict-sync/SKILL.md → 字典同步
|
|
52
|
-
✅ MCP 工具检查：wls_dict_query / wls_dict_upsert 均可用
|
|
53
|
-
✅ 已读取 .github/skills/sync/env.local.json → 网关 + token + sysAppNo + dict.moduleId
|
|
54
|
-
✅ 已读取 .github/reports/SYS_DICT_INFO.md → 本地字典基线
|
|
55
|
-
✅ 操作模式：{pull / push / audit}
|
|
56
|
-
✅ 目标字典码：{用户指定 / data.ts 扫描结果}
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
> Pre-flight 任一项失败（特别是 MCP 工具检查），立即停止并向用户报告，**不得**降级为手动调接口。
|
|
60
|
-
|
|
61
|
-
---
|
|
62
|
-
|
|
63
|
-
## 三种工作模式
|
|
64
|
-
|
|
65
|
-
### pull — 刷新本地基线
|
|
66
|
-
|
|
67
|
-
**触发词**：`刷新字典基线` / `拉字典`
|
|
68
|
-
|
|
69
|
-
**执行**：
|
|
70
|
-
1. 调用 MCP 工具 `wls_dict_query`（无参）
|
|
71
|
-
2. 工具返回当前应用域全部字典模块 + 字典项树
|
|
72
|
-
3. AI 解析返回结果，整理为 SYS_DICT_INFO.md 格式覆盖写入
|
|
73
|
-
4. 输出："共拉取 N 个字典码，M 个字典项"
|
|
74
|
-
|
|
75
|
-
> MCP 内部对应 `GET /system/business/dict/getDictionaryTreeData`，AI **无需关心**。
|
|
76
|
-
|
|
77
|
-
---
|
|
78
|
-
|
|
79
|
-
### push — 推送新增字典（核心模式）
|
|
80
|
-
|
|
81
|
-
**触发词**：`同步字典` / `创建字典` / `补字典`
|
|
82
|
-
|
|
83
|
-
#### Step 1：扫描 data.ts 中的字典引用
|
|
84
|
-
|
|
85
|
-
从用户指定范围扫描所有：
|
|
86
|
-
|
|
87
|
-
```typescript
|
|
88
|
-
logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
去重得到「当前用到的字典码集合」。
|
|
92
|
-
|
|
93
|
-
#### Step 2：与本地基线 + 线上对比（去重双保险）
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
① 读取 reports/SYS_DICT_INFO.md → 本地已知字典码
|
|
97
|
-
② 调用 wls_dict_query → 线上当前字典码（strSn 列表）
|
|
98
|
-
③ 待创建 = 用到的字典码 - 线上已有字典码
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
> **多人协同**：每人 env.local.json 不入 git。去重通过 ② 线上实时查询保证；后端 `strSn` 字段有唯一约束，并发场景下第二次创建会被服务端跳过，Skill 视为成功。
|
|
102
|
-
|
|
103
|
-
#### Step 3：Pre-flight 输出待新建清单，等待确认
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
📋 待同步字典清单：
|
|
107
|
-
新建：ORDER_STATUS（订单状态）— 含 4 项
|
|
108
|
-
新建：SALES_COMPANY（销售公司）— 含 3 项
|
|
109
|
-
跳过（线上已有）：PRODUCT_SEGMENT
|
|
110
|
-
确认执行？(yes/no)
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
#### Step 4：批量创建字典码 + 字典项
|
|
114
|
-
|
|
115
|
-
调用 MCP 工具 `wls_dict_upsert`（**逐个字典模块**调一次）：
|
|
116
|
-
|
|
117
|
-
```jsonc
|
|
118
|
-
// MCP 工具入参
|
|
119
|
-
{
|
|
120
|
-
"module": {
|
|
121
|
-
"strSn": "ORDER_STATUS",
|
|
122
|
-
"strName": "订单状态",
|
|
123
|
-
"sortPriority": "1",
|
|
124
|
-
"strLevel": 2
|
|
125
|
-
},
|
|
126
|
-
"items": [
|
|
127
|
-
{ "strSn": "0", "strName": "草稿", "strLevel": 2 },
|
|
128
|
-
{ "strSn": "1", "strName": "待审核", "strLevel": 2 },
|
|
129
|
-
{ "strSn": "2", "strName": "已通过", "strLevel": 2 },
|
|
130
|
-
{ "strSn": "3", "strName": "已驳回", "strLevel": 2 }
|
|
131
|
-
]
|
|
132
|
-
}
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
> 工具内部：模块不存在则创建并自动 re-query 取 id；字典项按 strSn 自动跳过已存在项。AI 无需手动管理 id。
|
|
136
|
-
|
|
137
|
-
#### Step 5：输出结果表 + 更新基线
|
|
138
|
-
|
|
139
|
-
| 字典码 | 字典名称 | 字典项数 | 状态 |
|
|
140
|
-
|---|---|---|---|
|
|
141
|
-
| ORDER_STATUS | 订单状态 | 4 | ✅ created |
|
|
142
|
-
| SALES_COMPANY | 销售公司 | 3 | ✅ created |
|
|
143
|
-
| PRODUCT_SEGMENT | 产品板块 | - | ⏭️ skipped（线上已有） |
|
|
144
|
-
|
|
145
|
-
执行完成后，将新建字典追加写入 `.github/reports/SYS_DICT_INFO.md`。
|
|
146
|
-
|
|
147
|
-
---
|
|
148
|
-
|
|
149
|
-
### audit — 仅检查，不调写接口
|
|
150
|
-
|
|
151
|
-
**触发词**：`字典审计` / `检查字典`
|
|
152
|
-
|
|
153
|
-
```
|
|
154
|
-
1. 扫描指定范围的 data.ts，收集所有 logicValue 字典码
|
|
155
|
-
2. 调用 wls_dict_query 获取线上现状
|
|
156
|
-
3. 对比 SYS_DICT_INFO.md 本地基线
|
|
157
|
-
4. 输出三类清单：
|
|
158
|
-
✅ 已在基线 + 线上（健康）
|
|
159
|
-
⚠️ data.ts 用到但缺失（建议执行 push）
|
|
160
|
-
💤 在基线但未被任何 data.ts 引用（可能已废弃）
|
|
161
|
-
5. 不调用任何写接口
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
---
|
|
165
|
-
|
|
166
|
-
## SYS_DICT_INFO.md — 本地基线格式
|
|
167
|
-
|
|
168
|
-
路径：`.github/reports/SYS_DICT_INFO.md`
|
|
169
|
-
|
|
170
|
-
```markdown
|
|
171
|
-
## ORDER_STATUS（订单状态）
|
|
172
|
-
|
|
173
|
-
| 值（strSn） | 显示名称（strName） | 备注 |
|
|
174
|
-
| ---------- | ------------------ | ---- |
|
|
175
|
-
| 0 | 草稿 | |
|
|
176
|
-
| 1 | 待审核 | |
|
|
177
|
-
| 2 | 已通过 | |
|
|
178
|
-
| 3 | 已驳回 | |
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
**字典码命名规范**：全大写 + 下划线，如 `ORDER_STATUS` / `SALES_COMPANY`。
|
|
182
|
-
|
|
183
|
-
---
|
|
184
|
-
|
|
185
|
-
## 冲突处理原则
|
|
186
|
-
|
|
187
|
-
| 场景 | 策略 |
|
|
188
|
-
|---|---|
|
|
189
|
-
| 本地新增、线上不存在 | 调 `wls_dict_upsert` 创建 |
|
|
190
|
-
| 字典码已存在、字典名不同 | 询问用户：以本地为准 / 保留线上 / 跳过 |
|
|
191
|
-
| 字典项 strSn 相同、strName 不同 | 询问用户决定（Skill 默认跳过，不覆盖） |
|
|
192
|
-
| 线上存在、本地无记录 | 仅在 audit 中报告，**绝不主动删除** |
|
|
193
|
-
|
|
194
|
-
---
|
|
195
|
-
|
|
196
|
-
## 与其他 Skill 联动
|
|
197
|
-
|
|
198
|
-
| Skill | 联动方式 |
|
|
199
|
-
|---|---|
|
|
200
|
-
| **page-codegen** | 生成 data.ts 时如 `logicValue` 不在基线中，报告末尾提示"建议运行 dict-sync 补齐" |
|
|
201
|
-
| **convention-audit** | 调用 audit 模式，"字典码未在基线"列为 🟡 偏差 |
|
|
202
|
-
| **menu-sync / permission-sync** | 共享 `skills/sync/env.local.json`，gatewayPath / token / sysAppNo 同一份 |
|
|
203
|
-
|
|
204
|
-
---
|
|
205
|
-
|
|
206
|
-
## MCP 不可用或调用失败时怎么办
|
|
207
|
-
|
|
208
|
-
见 `../_mcp-guardrail.md` §2 自愈闭环剧本。**原则**：先帮用户完善 `env.local.json` 里的 token / dict.moduleId，重试 MCP 工具。**绝不允许** AI 用 curl/PowerShell/fetch 绕开 MCP 手拼 HTTP。
|
|
1
|
+
---
|
|
2
|
+
name: dict-sync
|
|
3
|
+
description: "Use when: syncing data dictionary entries to the backend, pulling the current online dictionary baseline, or checking which dictionaries used in data.ts are missing from the system. Triggers on: 同步字典, 创建字典, 刷新字典基线, 字典对比, 字典审计, dict sync, create dict."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Skill: 字典同步（dict-sync）
|
|
7
|
+
|
|
8
|
+
将 `data.ts` 中引用的数据字典（`logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"`）同步到后端字典表，保持本地基线与线上一致。
|
|
9
|
+
|
|
10
|
+
> **与 menu-sync / permission-sync 对称**：同样读取本地基线 → 与线上对比 → 补齐差异。配置共用 `skills/sync/env.local.json`。
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 📖 必读公共护栏
|
|
15
|
+
|
|
16
|
+
本 Skill 遵守 `../_mcp-guardrail.md`（MCP 调用纪律与自愈闭环）。AI 首次执行 sync 类任务时先 `read_file` 加载它。
|
|
17
|
+
|
|
18
|
+
本 Skill 使用的 MCP 工具：`wls_dict_query` / `wls_dict_upsert`。调用失败时按 guardrail §2 剧本引导用户完善 `env.local.json` 后重试，**不得用 curl/手拼 HTTP 绕开 MCP**。
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 配置（统一配置文件）
|
|
23
|
+
|
|
24
|
+
读取 `.github/skills/sync/env.local.json`（已在 `.gitignore`，不入 git）：
|
|
25
|
+
|
|
26
|
+
```json
|
|
27
|
+
{
|
|
28
|
+
"gatewayPath": "http://192.168.10.50:9000",
|
|
29
|
+
"sysAppNo": "QjQuXy1kbKxZyjhS5N2",
|
|
30
|
+
"token": "eyJhbGci...",
|
|
31
|
+
"dict": {
|
|
32
|
+
"moduleId": "7C909G0U2F8HI7E305LV0135LSJ3UBIO"
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
| 字段 | 说明 |
|
|
38
|
+
|---|---|
|
|
39
|
+
| `gatewayPath` | 后端网关，末尾不加斜杠 |
|
|
40
|
+
| `sysAppNo` | 应用编码（非明文） |
|
|
41
|
+
| `token` | 纯 JWT，**不含 `bearer ` 前缀**（MCP 内部自动拼接） |
|
|
42
|
+
| `dict.moduleId` | 字典所属模块 ID（字典管理后台 Network 抓取） |
|
|
43
|
+
|
|
44
|
+
> 字段获取方式见同目录 `../menu-sync/env/guide.md`。
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Pre-flight 声明（执行前必须输出）
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
🚀 已触发技能 dict-sync/SKILL.md → 字典同步
|
|
52
|
+
✅ MCP 工具检查：wls_dict_query / wls_dict_upsert 均可用
|
|
53
|
+
✅ 已读取 .github/skills/sync/env.local.json → 网关 + token + sysAppNo + dict.moduleId
|
|
54
|
+
✅ 已读取 .github/reports/SYS_DICT_INFO.md → 本地字典基线
|
|
55
|
+
✅ 操作模式：{pull / push / audit}
|
|
56
|
+
✅ 目标字典码：{用户指定 / data.ts 扫描结果}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
> Pre-flight 任一项失败（特别是 MCP 工具检查），立即停止并向用户报告，**不得**降级为手动调接口。
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 三种工作模式
|
|
64
|
+
|
|
65
|
+
### pull — 刷新本地基线
|
|
66
|
+
|
|
67
|
+
**触发词**：`刷新字典基线` / `拉字典`
|
|
68
|
+
|
|
69
|
+
**执行**：
|
|
70
|
+
1. 调用 MCP 工具 `wls_dict_query`（无参）
|
|
71
|
+
2. 工具返回当前应用域全部字典模块 + 字典项树
|
|
72
|
+
3. AI 解析返回结果，整理为 SYS_DICT_INFO.md 格式覆盖写入
|
|
73
|
+
4. 输出："共拉取 N 个字典码，M 个字典项"
|
|
74
|
+
|
|
75
|
+
> MCP 内部对应 `GET /system/business/dict/getDictionaryTreeData`，AI **无需关心**。
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
### push — 推送新增字典（核心模式）
|
|
80
|
+
|
|
81
|
+
**触发词**：`同步字典` / `创建字典` / `补字典`
|
|
82
|
+
|
|
83
|
+
#### Step 1：扫描 data.ts 中的字典引用
|
|
84
|
+
|
|
85
|
+
从用户指定范围扫描所有：
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
去重得到「当前用到的字典码集合」。
|
|
92
|
+
|
|
93
|
+
#### Step 2：与本地基线 + 线上对比（去重双保险）
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
① 读取 reports/SYS_DICT_INFO.md → 本地已知字典码
|
|
97
|
+
② 调用 wls_dict_query → 线上当前字典码（strSn 列表）
|
|
98
|
+
③ 待创建 = 用到的字典码 - 线上已有字典码
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
> **多人协同**：每人 env.local.json 不入 git。去重通过 ② 线上实时查询保证；后端 `strSn` 字段有唯一约束，并发场景下第二次创建会被服务端跳过，Skill 视为成功。
|
|
102
|
+
|
|
103
|
+
#### Step 3：Pre-flight 输出待新建清单，等待确认
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
📋 待同步字典清单：
|
|
107
|
+
新建：ORDER_STATUS（订单状态）— 含 4 项
|
|
108
|
+
新建：SALES_COMPANY（销售公司）— 含 3 项
|
|
109
|
+
跳过（线上已有）：PRODUCT_SEGMENT
|
|
110
|
+
确认执行？(yes/no)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
#### Step 4：批量创建字典码 + 字典项
|
|
114
|
+
|
|
115
|
+
调用 MCP 工具 `wls_dict_upsert`（**逐个字典模块**调一次）：
|
|
116
|
+
|
|
117
|
+
```jsonc
|
|
118
|
+
// MCP 工具入参
|
|
119
|
+
{
|
|
120
|
+
"module": {
|
|
121
|
+
"strSn": "ORDER_STATUS",
|
|
122
|
+
"strName": "订单状态",
|
|
123
|
+
"sortPriority": "1",
|
|
124
|
+
"strLevel": 2
|
|
125
|
+
},
|
|
126
|
+
"items": [
|
|
127
|
+
{ "strSn": "0", "strName": "草稿", "strLevel": 2 },
|
|
128
|
+
{ "strSn": "1", "strName": "待审核", "strLevel": 2 },
|
|
129
|
+
{ "strSn": "2", "strName": "已通过", "strLevel": 2 },
|
|
130
|
+
{ "strSn": "3", "strName": "已驳回", "strLevel": 2 }
|
|
131
|
+
]
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
> 工具内部：模块不存在则创建并自动 re-query 取 id；字典项按 strSn 自动跳过已存在项。AI 无需手动管理 id。
|
|
136
|
+
|
|
137
|
+
#### Step 5：输出结果表 + 更新基线
|
|
138
|
+
|
|
139
|
+
| 字典码 | 字典名称 | 字典项数 | 状态 |
|
|
140
|
+
|---|---|---|---|
|
|
141
|
+
| ORDER_STATUS | 订单状态 | 4 | ✅ created |
|
|
142
|
+
| SALES_COMPANY | 销售公司 | 3 | ✅ created |
|
|
143
|
+
| PRODUCT_SEGMENT | 产品板块 | - | ⏭️ skipped（线上已有） |
|
|
144
|
+
|
|
145
|
+
执行完成后，将新建字典追加写入 `.github/reports/SYS_DICT_INFO.md`。
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
### audit — 仅检查，不调写接口
|
|
150
|
+
|
|
151
|
+
**触发词**：`字典审计` / `检查字典`
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
1. 扫描指定范围的 data.ts，收集所有 logicValue 字典码
|
|
155
|
+
2. 调用 wls_dict_query 获取线上现状
|
|
156
|
+
3. 对比 SYS_DICT_INFO.md 本地基线
|
|
157
|
+
4. 输出三类清单：
|
|
158
|
+
✅ 已在基线 + 线上（健康）
|
|
159
|
+
⚠️ data.ts 用到但缺失（建议执行 push）
|
|
160
|
+
💤 在基线但未被任何 data.ts 引用（可能已废弃）
|
|
161
|
+
5. 不调用任何写接口
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## SYS_DICT_INFO.md — 本地基线格式
|
|
167
|
+
|
|
168
|
+
路径：`.github/reports/SYS_DICT_INFO.md`
|
|
169
|
+
|
|
170
|
+
```markdown
|
|
171
|
+
## ORDER_STATUS（订单状态）
|
|
172
|
+
|
|
173
|
+
| 值（strSn） | 显示名称（strName） | 备注 |
|
|
174
|
+
| ---------- | ------------------ | ---- |
|
|
175
|
+
| 0 | 草稿 | |
|
|
176
|
+
| 1 | 待审核 | |
|
|
177
|
+
| 2 | 已通过 | |
|
|
178
|
+
| 3 | 已驳回 | |
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
**字典码命名规范**：全大写 + 下划线，如 `ORDER_STATUS` / `SALES_COMPANY`。
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## 冲突处理原则
|
|
186
|
+
|
|
187
|
+
| 场景 | 策略 |
|
|
188
|
+
|---|---|
|
|
189
|
+
| 本地新增、线上不存在 | 调 `wls_dict_upsert` 创建 |
|
|
190
|
+
| 字典码已存在、字典名不同 | 询问用户：以本地为准 / 保留线上 / 跳过 |
|
|
191
|
+
| 字典项 strSn 相同、strName 不同 | 询问用户决定（Skill 默认跳过，不覆盖） |
|
|
192
|
+
| 线上存在、本地无记录 | 仅在 audit 中报告，**绝不主动删除** |
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## 与其他 Skill 联动
|
|
197
|
+
|
|
198
|
+
| Skill | 联动方式 |
|
|
199
|
+
|---|---|
|
|
200
|
+
| **page-codegen** | 生成 data.ts 时如 `logicValue` 不在基线中，报告末尾提示"建议运行 dict-sync 补齐" |
|
|
201
|
+
| **convention-audit** | 调用 audit 模式，"字典码未在基线"列为 🟡 偏差 |
|
|
202
|
+
| **menu-sync / permission-sync** | 共享 `skills/sync/env.local.json`，gatewayPath / token / sysAppNo 同一份 |
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## MCP 不可用或调用失败时怎么办
|
|
207
|
+
|
|
208
|
+
见 `../_mcp-guardrail.md` §2 自愈闭环剧本。**原则**：先帮用户完善 `env.local.json` 里的 token / dict.moduleId，重试 MCP 工具。**绝不允许** AI 用 curl/PowerShell/fetch 绕开 MCP 手拼 HTTP。
|