chore: solidify guide P1 snapshot

docs/SHENZHEN_NATURAL_MUSEUM_DEV_SKILL_USAGE.md

@@ -0,0 +1,132 @@
+# shenzhen-natural-museum-dev Skill 使用说明
+
+本文档说明项目专用 Codex skill `shenzhen-natural-museum-dev` 的使用方式、触发场景和维护规则。该 skill 用于固化深圳自然博物馆 `frontend-miniapp` 项目的导览、三维模型、腾讯地图、静态资源、历史 demo 数据和 H5 质量标准。
+
+## Skill 位置
+
+- Skill 主文件：`.agents/skills/shenzhen-natural-museum-dev/SKILL.md`
+- Skill 展示元数据：`.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml`
+
+说明文档放在 `docs/` 下，而不是放进 skill 目录。skill 目录应保持精简，只保留 AI 执行任务所需的必要文件。
+
+## 什么时候使用
+
+处理以下任务时应使用该 skill：
+
+- 导览模块页面、组件、交互或数据流调整
+- 室内三维导览、Three.js、GLB/GLTF 模型加载、WebGL 性能问题
+- 腾讯地图、室外导览、地图 SDK 或地图标记逻辑调整
+- `static/nav-assets/app_nav_assets_v2_clean_20260609_075339` 资源包相关工作
+- `src/services/navAssets.ts` 导览数据服务相关工作
+- `src/assets/data` 历史 demo 数据清理、隔离或迁移
+- `route_graph`、`nav_data`、POI 坐标、路线规划能力判断
+- H5 适配、移动端遮挡、构建和质量门禁
+- 导览模块专项架构审计或上线风险审查
+
+默认只关注 H5 模式。除非任务明确提到“小程序”“mp-weixin”或“小程序构建”，否则不要把小程序兼容作为默认目标。
+
+## 如何触发
+
+在 Codex 任务中可以显式写明：
+
+```text
+请使用 shenzhen-natural-museum-dev skill，检查导览模块的 Three.js 模型加载问题。
+```
+
+也可以在任务描述里包含明确上下文，Codex 应能自动匹配：
+
+```text
+帮我修复室内三维导览切换后顶部菜单被遮挡的问题。
+```
+
+```text
+请检查腾讯地图和室内 3D 是否有耦合风险。
+```
+
+```text
+帮我清理导览模块里依赖 src/assets/data 的旧 demo 数据。
+```
+
+## Skill 固化的核心规则
+
+- 导览业务数据必须优先走 `src/services/navAssets.ts`。
+- 当前干净导览资源包为 `static/nav-assets/app_nav_assets_v2_clean_20260609_075339`。
+- `src/assets/data` 是历史 demo 数据区域，不应再作为当前导览模块的数据源。
+- 在 `route_graph` 和 `nav_data` 未准备并验证前，不应声明“真实馆内导航”或启用真实路线规划。
+- POI 坐标只能作为展示或位置预览候选，不能当作已认证导航锚点。
+- Three.js / GLB 室内三维逻辑应与腾讯地图 / 室外导览逻辑隔离。
+- Three.js/WebGL 当前按 H5 能力处理；不要默认增加小程序 fallback 或 mp-weixin 兼容工作。
+- 移动端顶部菜单、搜索、卡片、按钮和楼层控件不能被 3D canvas 遮挡。
+- 不做无关重构，不直接删除历史数据；先盘点引用、隔离影响，再按确认范围清理。
+
+## 推荐任务写法
+
+导览功能开发：
+
+```text
+请使用 shenzhen-natural-museum-dev skill，基于当前 clean nav assets 修改导览搜索结果跳转逻辑，不能依赖 src/assets/data 旧数据。
+```
+
+三维模型问题：
+
+```text
+请使用 shenzhen-natural-museum-dev skill，排查室内 3D 模型加载失败，并保证 H5 有加载中和失败兜底。
+```
+
+腾讯地图问题：
+
+```text
+请使用 shenzhen-natural-museum-dev skill，检查腾讯地图逻辑是否被室内导览改动影响，只读审计并给出证据文件。
+```
+
+历史数据清理：
+
+```text
+请使用 shenzhen-natural-museum-dev skill，先只读盘点 src/assets/data 旧 demo 数据在项目中的引用，不要删除文件。
+```
+
+架构审计：
+
+```text
+请使用 shenzhen-natural-museum-dev skill，对导览、腾讯地图、Three.js、静态资源和 H5 构建做一次只读架构审计。
+```
+
+## 验证要求
+
+涉及代码修改时，优先根据风险运行以下检查：
+
+```powershell
+pnpm type-check
+pnpm lint
+pnpm build:h5
+```
+
+注意：
+
+- `pnpm build:*` 会写入 `dist`，如果任务是只读审计，应先说明风险再执行。
+- `pnpm lint` 即使命令成功，警告也应视为技术债。
+- 导览 UI 改动后，应额外做 H5 冒烟检查：顶部菜单、室内 3D、开始导航/位置预览、搜索结果、路线详情页。
+- 只有用户明确要求小程序/mp-weixin 时，才额外运行 `pnpm build:mp-weixin` 或处理小程序兼容。
+
+## 维护方式
+
+更新项目架构标准时，优先修改：
+
+```text
+.agents/skills/shenzhen-natural-museum-dev/SKILL.md
+```
+
+修改后运行 skill 校验：
+
+```powershell
+$env:PYTHONUTF8='1'
+python C:\Users\Administrator\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents\skills\shenzhen-natural-museum-dev
+```
+
+如果展示名称、默认提示词或简短说明需要调整，再同步更新：
+
+```text
+.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml
+```
+
+不要在 skill 目录下新增 README、CHANGELOG 或临时说明文件；团队说明文档统一放在 `docs/` 下。