133 lines
5.1 KiB
Markdown
133 lines
5.1 KiB
Markdown
# 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/` 下。
|