戏剧国粹小助手（opera-expert）
一套已落地的「中国戏曲知识检索 + 唱腔示意」工程能力：内置 45 个剧种 / 曲种、173 部经典剧目、90 首经典曲段的
中文资料（单一数据源 data.json），可直接复制出一份完整工程（微信小程序三份副本 + 网页版），并提供同步、校验、
素材生成与数据修补的 PowerShell 工具链。
何时使用
- 查询某个剧种 / 曲种、剧目、唱段、声腔、行当、名家的资料
- 需要从零得到一套「检索 + 唱腔示意」的微信小程序 / 网页版工程
- 增改
data.json后需要同步三份副本、确认工程仍然完整 - 需要生成或重绘剧种水墨宣传画
- 需要处理唱段试听（合成唱腔示意旋律、排查无声 / 串音）
- 需要确认工程是否可正常运行（全量校验含无头浏览器真实渲染与交互自测）
能力清单
| 需求 | 入口 |
|---|---|
| 剧种 / 剧目 / 唱段 / 名家资料查询 | references/opera-index.md（45 剧种速查索引），或读取 assets/template/data.json 原文 |
| 字段规范与新增剧种 | references/data-schema.md |
| 从模板新建工程 | scripts/new_project.ps1 -Target <目标目录> |
| 修改数据后同步三份副本 | scripts/sync.ps1 -ProjectRoot <工程目录> |
| 全量校验（静态 + 数据 + 副本一致性 + 真实渲染） | scripts/validate.ps1 -ProjectRoot <工程目录> |
| 生成 / 重绘 45 张宣传画 | scripts/gen_media.ps1 -ProjectRoot <工程目录> |
| 补全剧目主演名家 | scripts/patch_artists.ps1 -ProjectRoot <工程目录> |
| 技能自检（结构与脚本语法） | scripts/validate_skill.ps1 |
| 还原小程序私有格式文件 | scripts/restore_wxapp.ps1（从 references/miniprogram-wxss-wxml.md 写回 .wxss / .wxml） |
| 同步 / 素材 / 音频排障 | references/workflow-faq.md |
| 完整可运行工程（源码 + 数据 + 45 张宣传画） | assets/template/ |
所有脚本均接受 -ProjectRoot（默认当前目录），加 -Help 可查看用法。
标准工作流
- 答问类：先读
references/opera-index.md定位剧种；需要细节时再读工程内的assets/template/data.json
对应字段并原样引用，不要凭记忆编造剧目、名家或年代。 - 新建工程：执行
scripts/new_project.ps1 -Target <目标目录>，脚本复制assets/template/并自动调用
scripts/sync.ps1生成数据模块与三份副本。 - 改数据：只改工程根目录
data.json（唯一数据源，中文键），然后依次执行
scripts/sync.ps1、scripts/validate.ps1。 - 换宣传画：先
scripts/gen_media.ps1，再scripts/sync.ps1（宣传画编号与data.json剧种顺序一一对应）。 - 发布前确认：
scripts/validate.ps1输出ALL CHECKS PASSED，且小程序主包 < 2 MB。
常用命令
# 新建一套完整工程（含同步）
powershell -NoProfile -File scripts\new_project.ps1 -Target D:\my-opera
# 维护既有工程
powershell -NoProfile -File scripts\sync.ps1 -ProjectRoot D:\my-opera
powershell -NoProfile -File scripts\validate.ps1 -ProjectRoot D:\my-opera
目录结构
opera-expert/
├── SKILL.md 本文件（技能入口）
├── README.md 安装与使用说明
├── references/ opera-index.md、data-schema.md、workflow-faq.md、
│ miniprogram-wxss-wxml.md（.wxss/.wxml 源码备份）
├── scripts/ new_project / sync / validate / gen_media / patch_artists / validate_skill
└── assets/template/ 可直接复制运行的完整工程模板（含 data.json 与 45 张宣传画）
关键约束
assets/template/data.json是唯一数据源；data.js（小程序与网页版）、三份副本、宣传画均为生成物，勿手工编辑- 三份小程序副本（根、
miniprogram/、微信小程序/）必须逐字节一致，由scripts/sync.ps1保证 - 宣传画文件名
opera-01..45.jpg与data.json的剧种顺序一一对应；顺序变更须重绘 - 唱段音频不内置：由
pages/index/synth.js按「腔系 + 行当 + 板式 + 唱词」实时合成 WAV，
小程序写入USER_DATA_PATH后播放，网页端转 Blob URL；填入真实音源链接后自动改用正式音源 - 分发到 SkillHub 等平台时，包内不含
.wxss/.wxml（文件类型白名单限制）：源码全文在
references/miniprogram-wxss-wxml.md，还原执行scripts/restore_wxapp.ps1 - 小程序主包上限 2 MB（模板约 864 KB），新增素材须复核包体
- 检索为纯前端：剧种名、别名、剧目名、唱词、声腔、行当、名家、地域、年代、正文均可命中，结果按相关度排序、上限 30 条
- 网页版不使用
fetch，数据与合成器用<script>载入，支持file://直接打开
运行环境
- 脚本为 PowerShell（Windows PowerShell 5.1 或 PowerShell 7）：
powershell -NoProfile -File <脚本> - 所有操作为本地文件处理：仅加载系统自带程序集
System.Drawing/System.IO.Compression - 不发起网络请求、不经 Windows 脚本宿主执行、不启动外部进程、不写注册表、也无法绕过执行策略
安全边界
- 执行写操作（
new_project/sync/gen_media/patch_artists）前必须显式给出目标目录，
并先向用户复述该目录；不得写入技能目录之外的隐含路径 scripts/gen_media.ps1会先删除并重绘目标工程里的剧种宣传画目录（opera-01..45.jpg），目标目录写错会造成素材丢失，务必核对- 不要把用户工程中的私有信息写入本技能包的任何文件；引用外部资料时须注明出处
输出约定
- 答问：先给结论，再给「历史渊源 / 代表行当 / 经典剧目 / 代表人物」结构化要点，末尾标注数据来源文件
- 工程操作：报告「目标目录 → 执行动作 → 校验结果」，校验未通过须列出失败项而非笼统结论
- 排障：按
references/workflow-faq.md的步骤给出最小复现与修复动作
参考资料
references/opera-index.md— 45 剧种速查索引（别名、起源地、形成时间、代表人物、经典剧目）references/data-schema.md—data.json字段规范、示例与校验规则references/workflow-faq.md— 同步 / 校验 / 素材 / 音频常见问题与排查步骤assets/template/— 可直接复制运行的完整工程模板
