# Shenzhen Natural Museum Dev Skill 对话纪要 日期：2026-06-11 ## 背景 本次对话围绕 `shenzhen-natural-museum-dev` skill 的定位、完整性和专业性展开。当前期望定位已明确为： > 移动端自然博物馆三维导览 skill。 该 skill 应服务于移动端自然博物馆导览应用，重点覆盖 H5/移动端三维导览、馆内 3D 展示、POI/位置预览、楼层/全馆模型切换、数据 readiness、业务逻辑审核、工程架构审核和数据/展示层解耦。 ## 当前 Skill 检查结论 已检查 `.agents/skills/shenzhen-natural-museum-dev/SKILL.md`。 结论：基础合格，但还不是完整的“移动端自然博物馆三维导览专业 skill”。 - 已通过 `skill-creator` 的 `quick_validate.py` 校验，输出为 `Skill is valid!`。 - 文件结构包含 `SKILL.md` 和 `agents/openai.yaml`。 - 现有内容已经覆盖 H5 导览、Three.js/GLB、Tencent Map、clean nav assets、导览数据访问层、数据 provider/adapter、三维导览数据审核、浏览器用户流审核、legacy demo data 边界等。 ## 三类审核模块判断 ### 数据审核模块 状态：合格。 证据： - `SKILL.md` 中存在明确标题：`三维导览数据审核模块`。 - 模块覆盖 clean package、manifest、GLB/GLTF、POI index、floor definitions、connector data、`route_graph`、`nav_data`、`src/services/navAssets.ts`、导览数据访问层、Provider/Adapter、路线 readiness 等。 ### 项目工程架构审核模块 状态：部分具备，但不完整。 现有内容： - `数据源标准` 中已经有导览数据访问层、Provider、Adapter、静态数据源/API 数据源、领域模型边界等要求。 - `description` 中提到 architecture reviews。 不足： - 没有独立的“项目工程架构审核模块”。 - 缺少针对页面层、组件层、数据服务层、ThreeMap 渲染层、状态管理、H5/mp 边界、canvas 层级、资源加载生命周期的工程架构审核清单。 ### 业务审核模块 状态：部分具备，但不完整。 现有内容： - `Browser User Flow Closure Testing` 可用于用户流程闭环测试。 - `3D Guide User Audit Module` 可用于移动端 3D 导览体验审核。 - 已覆盖真实用户任务、控件可见性、状态丢失、死路、伪导航文案、route readiness 边界等。 不足： - 没有独立命名为“业务逻辑审核模块”的模块。 - 缺少固定的业务审核输出结构，例如 P1/P2/P3、源码审核/浏览器验证分离、已实现/部分实现/缺失/数据不足分离。 ## 重新定位后的判断 如果定位为“深圳自然博物馆 frontend-miniapp H5 项目开发规范”，当前 skill 基本合格。 如果定位为“移动端自然博物馆三维导览 skill”，当前 skill 还需要加强： - 移动端三维导览业务逻辑审核模块。 - 移动端三维导览工程架构审核模块。 - 自然博物馆导览专业语义模块。 - 数据层与展示层解耦的硬性架构红线。 ## 数据层与展示层解耦原则 本对话明确提出：前端应用中数据层和前端展示层必须解耦。 该原则应作为 skill 的核心架构红线，而不是普通建议。 ### 推荐分层 ```text 数据源层 static nav-assets / CMS API / 后端 API / IMDF / BIM 导出 ↓ Provider 数据源提供器 StaticProvider / ApiProvider / FutureImdfProvider ↓ Adapter 数据适配器 把原始字段转换成统一导览领域模型 ↓ Guide Repository / Guide Data Access Layer 统一查询 floors、POI、模型、讲解、位置预览、route readiness ↓ Store / Composables / Use Cases 页面状态：当前楼层、全馆/单层、搜索词、选中 POI、是否可导航 ↓ Presentation ViewModel 给页面和 ThreeMap 的轻量展示数据 ↓ 前端展示层 GuideMapShell / ThreeMap / Search / Cards / Floor Switcher ``` ### 展示层不应直接依赖 - `static/nav-assets/*.json` 原始结构。 - 后端 API 原始字段。 - GLB manifest 的路径拼接规则。 - POI 原始坐标格式。 - `route_graph/nav_data` 是否存在的散落判断。 - 楼层 label / floorId 的重复转换逻辑。 ### 展示层只应消费领域模型或 ViewModel 推荐领域模型包括： - `GuideVenue` - `GuideBuilding` - `GuideFloor` - `GuideSpace` - `GuidePoi` - `GuideCategory` - `GuideModelAsset` - `GuideConnector` - `GuideLocationPreview` - `GuideRouteReadiness` - `GuideRouteGraph` - `GuideExplainMedia` ### P1 级架构问题示例 - 页面或组件直接读取 `static/nav-assets/*.json`。 - 页面直接依赖后端 API 原始字段。 - 组件内部重复实现 POI、floor、category、model path 转换。 - 真实导航 readiness 判断散落在 UI 层。 - 展示层把预览 POI 当成真实导航锚点。 ## 专业前端方案参考 本次联网查找后，较适合作为专业方案参考的方向包括： - IMDF：OGC 馆内地图数据标准，强调馆内 orientation、navigation、discovery。 - ArcGIS Indoors：馆内设施、楼层、单元、路径等信息模型。 - Mappedin：商业馆内地图 SDK 的楼层、位置、空间数据模型。 - Khronos glTF：3D 资产传输和运行时加载标准。 - Vue Composables：封装可复用 stateful logic。 - Pinia：前端 store 的 state/getters/actions。 - TanStack Query：server state 缓存、请求状态、刷新、去重。 参考链接： - https://docs.ogc.org/cs/20-094/index.html - https://doc.esri.com/en/arcgis-pro/latest/help/data/indoors/arcgis-indoors-information-model.html - https://www.khronos.org/gltf/ - https://vuejs.org/guide/reusability/composables - https://pinia.vuejs.org/core-concepts/ - https://tanstack.com/query/latest ## 网上同类 Skill 查找结论 已查到的小程序相关 skill 多为泛小程序开发，而非自然博物馆三维导览垂直 skill。 代表性方向： - TencentCloudBase `miniprogram-development`：偏微信小程序、CloudBase、预览部署、认证、AI 模型调用。 - `wechat-miniapp-factory`：偏小程序脚手架、校验、提交前预审。 - `wechat-miniprogram`：偏微信小程序官方文档、WXML/WXSS/WXS、API、组件、开放能力、性能优化。 - `wechat-devtools-diagnostics-skill`：偏 Windows 下微信开发者工具诊断。 结论： - 暂未找到“自然博物馆 / 场馆导览 / 馆内 3D / POI / 路线数据审核”这种垂直专业 skill。 - 当前 `shenzhen-natural-museum-dev` 的价值在于项目垂直和三维导览垂直，应继续强化，而不是直接照搬泛小程序 skill。 ## 建议后续补强方向 ### 1. 增加移动端三维导览业务逻辑审核模块 建议覆盖： - 初始馆外/馆内状态。 - 进入馆内后默认完整建筑模型。 - 全馆/单层切换。 - 楼层切换。 - POI 搜索和聚焦。 - 顶部“导览 / 讲解”切换。 - 搜索、卡片、工具按钮是否可见可点击。 - 伪导航、伪定位、伪路线承诺文案。 - 源码审核和浏览器交互验证必须分离标注。 - 输出 P1/P2/P3。 ### 2. 增加移动端三维导览工程架构审核模块 建议覆盖： - Page 层是否只组合业务状态，不直接解析数据源。 - GuideMapShell 是否只承担导览壳、控件承载、模式切换。 - ThreeMap 是否只承担 3D 渲染、相机、模型加载、POI 高亮，不承载业务数据转换。 - navAssets 或 successor service 是否作为唯一导览数据访问层。 - Provider/Adapter 是否隔离静态包和未来 API。 - H5 和 mp-weixin 是否清楚分界。 - 3D canvas 是否可能覆盖移动端 UI 控件。 - 资源加载、dispose、错误恢复是否具备。 ### 3. 增加自然博物馆导览专业语义模块 建议明确自然博物馆导览中的业务对象： - 展厅。 - 展项。 - 设施。 - 入口。 - 楼层。 - 展区。 - 讲解。 - 位置预览。 - 真实路线规划 readiness。 并明确当前阶段只能描述为： > 馆内 3D 展示 + POI/位置预览。 除非 `route_graph/nav_data` 已接入并验证，否则不能宣称真实馆内导航、路线规划、到达引导或定位精度。