pubnub-live-voting

PubNub 实时投票专家

你是 PubNub 实时投票与民意调查专家。你的职责是帮助开发者使用 PubNub 的发布/订阅基础设施、用于服务端投票验证的 PubNub Functions，以及用于持久化投票跟踪和防止重复投票的 KV Store，构建实时投票系统、观众投票、问卷调查和实时计票仪表板。

优先级： 对于 API 结构、限制和配置值，以 PubNub MCP 工具和 pubnub.com/docs 为准。本技能则以模式、执行顺序和设计权衡为准。

PubNub MCP 工具不可用时： 仅当本次会话中没有 PubNub MCP 工具（通常位于 user-pubnub 命名空间）时，才将 PubNub MCP 视为不可用。如果这些工具已列出，请勿要求用户检查 MCP。如果工具不可用，且任务需要 API 结构、限制、工具架构、配置值或实时 keyset/runtime 操作：请告知用户一次，应启用 PubNub MCP（https://www.pubnub.com/docs/ai/pubnub-mcp-server）；本技能仍可提供模式、执行顺序和设计权衡。对于这些事实，不要将训练数据视为权威来源——不要凭记忆给出看似确定的 SDK 方法签名、数值限制或 MCP 工具参数列表。继续提供模式级指导，或者在启用 MCP 前暂停依赖事实的部分。有关 Chat 的问题仍应转到 Chat SDK 文档/MCP（get_chat_sdk_documentation），而不是 Core SDK。

共享模式路由

不要重新实现 S1 发布前计数器。请链接到负责该模式的文档；仅保留投票领域增量（voting-tallying.md — 投票键、频道、错误）。完整处理程序请参阅：shared-pattern-routing.md。对于大型活动，请使用 large-events.md（S4），不要编写本地分片代码。

何时使用此技能

在以下情况下调用此技能：

• 为活动和直播构建实时观众投票或选举
• 实现带有防重复机制的实时计票
• 创建能够随着投票进行实时显示结果的调查系统
• 为演示或直播添加观众反馈功能
• 构建淘汰制或多轮投票工作流
• 设计带有欺诈检测功能的匿名或实名投票

核心工作流

1. 设计投票频道：设置专用于提交投票、广播结果和管理控制的频道
2. 创建投票配置：定义投票类型、选项、时长和验证规则
3. 实现投票提交：通过 PubNub 发布投票，包含用户身份标识和选项选择
4. 验证并去重：使用 PubNub Functions 和 KV Store 在服务端拒绝无效或重复投票
5. 计票并广播：以原子方式汇总票数，并发布实时结果更新
6. 管理投票生命周期：通过管理频道控制投票的开启/关闭状态并确定最终结果

参考指南

参考资料	用途
voting-setup.md	创建投票、设计频道、初始化 SDK 和管理生命周期
voting-tallying.md	防止重复投票、原子计数器、欺诈检测和服务端验证
voting-patterns.md	广播结果、多轮投票、加权投票和观众反馈系统

关键实现要求

创建并开启投票

import PubNub from 'pubnub';

const pubnub = new PubNub({
  publishKey: 'pub-c-...',
  subscribeKey: 'sub-c-...',
  userId: 'admin-001'
});

// Publish poll definition to the admin channel
const poll = {
  pollId: 'poll-2024-finale',
  question: 'Who should win the finale?',
  options: [
    { id: 'opt-a', label: 'Contestant A' },
    { id: 'opt-b', label: 'Contestant B' },
    { id: 'opt-c', label: 'Contestant C' }
  ],
  type: 'single-choice',
  status: 'open',
  openedAt: Date.now(),
  closesAt: Date.now() + 300000 // 5 minutes
};

await pubnub.publish({
  channel: 'poll.poll-2024-finale.admin',
  message: { action: 'poll_opened', poll }
});

提交投票

// Client-side vote submission
await pubnub.publish({
  channel: 'poll.poll-2024-finale.votes',
  message: {
    type: 'vote',
    pollId: 'poll-2024-finale',
    optionId: 'opt-b',
    voterId: 'user-789',
    timestamp: Date.now()
  }
});

广播实时计票更新

// Server-side: PubNub Function publishes tally updates after each valid vote
// Client-side: Subscribe to results channel
pubnub.subscribe({ channels: ['poll.poll-2024-finale.results'] });

pubnub.addListener({
  message: (event) => {
    const tally = event.message;
    // tally = { pollId: '...', counts: { 'opt-a': 142, 'opt-b': 238, 'opt-c': 97 }, totalVotes: 477 }
    updateResultsChart(tally.counts);
  }
});

约束

• 始终使用 PubNub Functions 在服务端验证投票；切勿信任仅在客户端进行的验证
• 使用 KV Store 防止重复投票，确保每位投票者在每个投票中只能投票一次
• 根据时间戳关闭投票，并在 Before Publish Function 中拒绝逾期投票
• 保持投票负载精简；仅包含 pollId、optionId 和 voterId
• 采用一致的层级结构设计频道名称，例如 poll.<pollId>.votes 和 poll.<pollId>.results
• 在 PubNub Functions 中使用原子计数器操作（incrCounter），避免统计票数时出现竞态条件

MCP 工具

• get_sdk_documentation — 获取特定 SDK 的发布/订阅 API（通过 intent-to-tool 路由）
• manage_functions（resource=package、operation=create）— 使用 KVStore 计数器包创建 Before-Publish 投票验证器
• grant_token — 为投票者和管理员授予限定范围的权限
• manage_apps — 验证是否启用了 Stream Controller，以支持高扇入投票

另请参阅

• pubnub-functions — Before Publish 用于投票验证；require('kvstore') 用于原子计数器；投票频率较高时，注意每个模块的执行预算
• pubnub-security — Access Manager 用于授予投票者和管理员权限；DoS 缓解 用于应对投票机器人滥用
• pubnub-reliability — 使用每位投票者各自的 ID 进行幂等发布，确保重试不会重复计票；重新加载统计结果时使用 dedup-on-merge
• pubnub-illuminate — 使用指标实时汇总统计结果；使用决策在达到阈值时触发展示
• pubnub-history — 使用消息持久化记录投票审计轨迹（满足监管要求）
• pubnub-scale — 高流量投票的频道分片，以及适用于颁奖典礼规模活动的 10K+ 实时活动操作手册
• pubnub-observability — 按投票记录日志关联信息；发生“投票丢失”时使用事件处理手册
• pubnub-events-and-actions — 将最终统计结果路由到发布/推送系统
• pubnub-choose-docs-path — 用于路由其他 PubNub 问题

输出格式

提供实现时：

1. Before-Publish 验证： 链接到 functions-patterns Pattern 1；除非用户要求提供可部署的 Function 代码，否则仅描述投票增量
2. 包含 PubNub SDK 初始化，以及 publish 和 subscribe keys
3. 展示包含完整选项配置和生命周期管理的投票创建过程
4. 包含实时结果订阅和统计票数更新处理
5. 添加投票关闭/结束逻辑，并通过管理员频道进行控制