frontend-miniapp/docs/shenzhen-natural-museum-dev-skill-dialogue-notes-2026-06-11.md

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 的核心架构红线，而不是普通建议。

推荐分层

数据源层
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 已接入并验证，否则不能宣称真实馆内导航、路线规划、到达引导或定位精度。