velt-presence-best-practices

本技能是 Velt 实时用户在线状态与光标跟踪功能的实现指南，包含 8 个类别共 15 条规则，适用于 React、Next.js 及 Web 应用。用途包括：添加展示在线成员的头像、配置不活跃超时（away/offline 状态）、在画布或页面上实现实时光标跟踪、订阅在线数据或用户状态变化、按位置或文档过滤在线状态、用 wireframes 定制头像界面、实现 flock mode（follow me）共享导航会话，以及排查在线状态不显示或用户显示离线的问题。规则按优先级分为核心设置（CRITICAL，如 core-auth-provider 要求使用 VeltProvider 的 authProvider 而非 identify()、core-setup 添加 VeltPresence 组件、core-document-setup 设置文档上下文）、数据访问（HIGH，usePresenceData、usePresenceEventCallback、getPresenceElement、getData、on）、配置（HIGH-MEDIUM，含不活跃超时、最大用户数、自身可见性、按位置过滤、flock mode 的 enableFlockMode、startFollowingUser/stopFollowingUser、onNavigate 回调与 defaultFlockNavigation）、光标（VeltCursor）、事件（在线/离开/离线状态转换订阅）、界面定制（VeltPresenceWireframe）、wireframe 变量（通过 componentConfig.<path> 模板变量绑定 velt-data/velt-if/velt-class）和调试。使用时从 AGENTS.md 压缩索引入手，再查阅 rules/shared 下各规则文件；每条规则含原因说明、正确代码示例、验证清单和官方文档指引。限制：资料未提供具体安装命令、定价与平台支持细节。