docs: add skill dialogue notes
This commit is contained in:
@@ -0,0 +1,225 @@
|
||||
# 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` 已接入并验证，否则不能宣称真实馆内导航、路线规划、到达引导或定位精度。
|
||||
|
||||
Reference in New Issue
Block a user