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 任务中可以显式写明：

请使用 shenzhen-natural-museum-dev skill，检查导览模块的 Three.js 模型加载问题。

也可以在任务描述里包含明确上下文，Codex 应能自动匹配：

帮我修复馆内三维导览切换后顶部菜单被遮挡的问题。

请检查腾讯地图和馆内 3D 是否有耦合风险。

帮我清理导览模块里依赖 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 遮挡。
不做无关重构，不直接删除历史数据；先盘点引用、隔离影响，再按确认范围清理。

验证要求

涉及代码修改时，优先根据风险运行以下检查：

pnpm type-check
pnpm lint
pnpm build:h5

注意：

pnpm build:* 会写入 dist，如果任务是只读审计，应先说明风险再执行。
pnpm lint 即使命令成功，警告也应视为技术债。
导览 UI 改动后，应额外做 H5 冒烟检查：顶部菜单、馆内 3D、开始导航/位置预览、搜索结果、路线详情页。
只有用户明确要求小程序/mp-weixin 时，才额外运行 pnpm build:mp-weixin 或处理小程序兼容。

维护方式

更新项目架构标准时，优先修改：

.agents/skills/shenzhen-natural-museum-dev/SKILL.md

修改后运行 skill 校验：

$env:PYTHONUTF8='1'
python C:\Users\Administrator\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents\skills\shenzhen-natural-museum-dev

如果展示名称、默认提示词或简短说明需要调整，再同步更新：

.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml

不要在 skill 目录下新增 README、CHANGELOG 或临时说明文件；团队说明文档统一放在 docs/ 下。

5.1 KiB Raw Blame History Unescape Escape