| name | dict-sync |
| 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. |
Skill: 字典同步（dict-sync）
将 data.ts 中引用的数据字典（logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"）同步到后端字典表，保持本地基线与线上一致。
与 menu-sync / permission-sync 对称：同样读取本地基线 → 与线上对比 → 补齐差异。配置共用 skills/sync/env.local.json。
📖 必读公共护栏
本 Skill 遵守 ../_mcp-guardrail.md（MCP 调用纪律与自愈闭环）。AI 首次执行 sync 类任务时先 read_file 加载它。
本 Skill 使用的 MCP 工具：wls_dict_query / wls_dict_upsert。调用失败时按 guardrail §2 剧本引导用户完善 env.local.json 后重试，不得用 curl/手拼 HTTP 绕开 MCP。
配置（统一配置文件）
读取 .github/skills/sync/env.local.json（已在 .gitignore，不入 git）：
{
"gatewayPath": "http://192.168.10.50:9000",
"sysAppNo": "QjQuXy1kbKxZyjhS5N2",
"token": "eyJhbGci...",
"dict": {
"moduleId": "7C909G0U2F8HI7E305LV0135LSJ3UBIO"
}
}
| 字段 | 说明 |
|---|
gatewayPath | 后端网关，末尾不加斜杠 |
sysAppNo | 应用编码（非明文） |
token | 纯 JWT，不含 bearer 前缀（MCP 内部自动拼接） |
dict.moduleId | 字典所属模块 ID（字典管理后台 Network 抓取） |
字段获取方式见同目录 ../menu-sync/env/guide.md。
Pre-flight 声明（执行前必须输出）
🚀 已触发技能 dict-sync/SKILL.md → 字典同步
✅ MCP 工具检查：wls_dict_query / wls_dict_upsert 均可用
✅ 已读取 .github/skills/sync/env.local.json → 网关 + token + sysAppNo + dict.moduleId
✅ 已读取 .github/reports/SYS_DICT_INFO.md → 本地字典基线
✅ 操作模式：{pull / push / audit}
✅ 目标字典码：{用户指定 / data.ts 扫描结果}
Pre-flight 任一项失败（特别是 MCP 工具检查），立即停止并向用户报告，不得降级为手动调接口。
三种工作模式
pull — 刷新本地基线
触发词：刷新字典基线 / 拉字典
执行：
- 调用 MCP 工具
wls_dict_query（无参）
- 工具返回当前应用域全部字典模块 + 字典项树
- AI 解析返回结果，整理为 SYS_DICT_INFO.md 格式覆盖写入
- 输出："共拉取 N 个字典码，M 个字典项"
MCP 内部对应 GET /system/business/dict/getDictionaryTreeData，AI 无需关心。
push — 推送新增字典（核心模式）
触发词：同步字典 / 创建字典 / 补字典
Step 1：扫描 data.ts 中的字典引用
从用户指定范围扫描所有：
logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"
去重得到「当前用到的字典码集合」。
Step 2：与本地基线 + 线上对比（去重双保险）
① 读取 reports/SYS_DICT_INFO.md → 本地已知字典码
② 调用 wls_dict_query → 线上当前字典码（strSn 列表）
③ 待创建 = 用到的字典码 - 线上已有字典码
多人协同：每人 env.local.json 不入 git。去重通过 ② 线上实时查询保证；后端 strSn 字段有唯一约束，并发场景下第二次创建会被服务端跳过，Skill 视为成功。
Step 3：Pre-flight 输出待新建清单，等待确认
📋 待同步字典清单：
新建：ORDER_STATUS（订单状态）— 含 4 项
新建：SALES_COMPANY（销售公司）— 含 3 项
跳过（线上已有）：PRODUCT_SEGMENT
确认执行？(yes/no)
Step 4：批量创建字典码 + 字典项
调用 MCP 工具 wls_dict_upsert（逐个字典模块调一次）：
{
"module": {
"strSn": "ORDER_STATUS",
"strName": "订单状态",
"sortPriority": "1",
"strLevel": 2
},
"items": [
{ "strSn": "0", "strName": "草稿", "strLevel": 2 },
{ "strSn": "1", "strName": "待审核", "strLevel": 2 },
{ "strSn": "2", "strName":
工具内部：模块不存在则创建并自动 re-query 取 id；字典项按 strSn 自动跳过已存在项。AI 无需手动管理 id。
Step 5：输出结果表 + 更新基线
| 字典码 | 字典名称 | 字典项数 | 状态 |
|---|
| ORDER_STATUS | 订单状态 | 4 | ✅ created |
| SALES_COMPANY | 销售公司 | 3 | ✅ created |
| PRODUCT_SEGMENT | 产品板块 | - | ⏭️ skipped（线上已有） |
执行完成后，将新建字典追加写入 .github/reports/SYS_DICT_INFO.md。
audit — 仅检查，不调写接口
触发词：字典审计 / 检查字典
1. 扫描指定范围的 data.ts，收集所有 logicValue 字典码
2. 调用 wls_dict_query 获取线上现状
3. 对比 SYS_DICT_INFO.md 本地基线
4. 输出三类清单：
✅ 已在基线 + 线上（健康）
⚠️ data.ts 用到但缺失（建议执行 push）
💤 在基线但未被任何 data.ts 引用（可能已废弃）
5. 不调用任何写接口
SYS_DICT_INFO.md — 本地基线格式
路径：.github/reports/SYS_DICT_INFO.md
## ORDER_STATUS（订单状态）
| 值（strSn） | 显示名称（strName） | 备注 |
| ---------- | ------------------ | ---- |
| 0 | 草稿 | |
| 1 | 待审核 | |
| 2 | 已通过 | |
| 3 | 已驳回 | |
字典码命名规范：全大写 + 下划线，如 ORDER_STATUS / SALES_COMPANY。
冲突处理原则
| 场景 | 策略 |
|---|
| 本地新增、线上不存在 | 调 wls_dict_upsert 创建 |
| 字典码已存在、字典名不同 | 询问用户：以本地为准 / 保留线上 / 跳过 |
| 字典项 strSn 相同、strName 不同 | 询问用户决定（Skill 默认跳过，不覆盖） |
| 线上存在、本地无记录 | 仅在 audit 中报告，绝不主动删除 |
与其他 Skill 联动
| Skill | 联动方式 |
|---|
| page-codegen | 生成 data.ts 时如 logicValue 不在基线中，报告末尾提示"建议运行 dict-sync 补齐" |
| convention-audit | 调用 audit 模式，"字典码未在基线"列为 🟡 偏差 |
| menu-sync / permission-sync | 共享 skills/sync/env.local.json，gatewayPath / token / sysAppNo 同一份 |
MCP 不可用或调用失败时怎么办
见 ../_mcp-guardrail.md §2 自愈闭环剧本。原则：先帮用户完善 env.local.json 里的 token / dict.moduleId，重试 MCP 工具。绝不允许 AI 用 curl/PowerShell/fetch 绕开 MCP 手拼 HTTP。
