| 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": "已通过", "strLevel": 2 },
{ "strSn": "3", "strName": "已驳回", "strLevel": 2 }
]
}
工具内部:模块不存在则创建并自动 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。