# 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_20260611_093623` 资源包相关工作
- `src/data/providers/staticNavAssetsProvider.ts`、`src/repositories/GuideRepository.ts`、`src/repositories/GuideModelRepository.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 固化的核心规则

- 导览业务数据必须优先走 Provider / Adapter / Repository / UseCase 边界，不再新增 `src/services/navAssets.ts` 兼容服务依赖。
- 当前干净导览资源包为 `static/nav-assets/app_nav_assets_v2_clean_20260611_093623`。
- `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/` 下。