Pouchy 伴侣 × 德州扑克 — 工具接入指引(可直接转发给开发)

目标:让伴侣不只"陪玩解说",还能在玩家用语音或文字开口时,在你的游戏里动手 (暂停、开关提示、调音量、切大厅、甚至按要求出牌),并且这段经历会被记住。 基线:SDK ≥ 0.5.0,baseUrl: 'https://pouchy.ai'(用 www,apex 会跳转)。

1. 一次性把"能动手"打开

import { createCompanion } from '@pouchy_ai/companion-sdk';

const companion = createCompanion({
  baseUrl: 'https://pouchy.ai',
  token: PLAYER_TOKEN,
  surface: 'poker-table',
  modalities: ['text', 'voice'],

  // ① 声明你的德州专用动作(可选,但更精准)。也可以一个都不声明,
  //    直接用下面 ② 的通用动词。
  tools: [
    { name: 'poker_action', description: '按玩家要求在当前手牌执行一个动作。涉及筹码,执行前由游戏侧二次确认。',
      parameters: { type:'object', properties:{
        move: { type:'string', description: 'fold | check | call | raise | allin' },
        amount: { type:'number', description: 'raise 时的加注额(可选)' }
      }, required:['move'] } }
  ],

  // ② 让伴侣"主动想得起来用工具"的提示词 —— 见第 4 节,强烈建议填。
  appContext: { name: 'Agent Poker Club', description: POKER_APP_PROMPT }
});

await companion.connect();
companion.start();                         // 文字/事件流
const call = await companion.connectCall({ locale: 'zh' });   // 语音陪玩

只要你声明了 tools 或 handles,SDK 会自动把 5 个通用 host-control 动词 一起提供给通话(无需你声明):invoke_action、set_feature、set_value、 navigate、highlight。语音(EL/OpenAI)和文字都能触发。

2. 一份 onToolCall 处理器(语音 + 文字共用)

companion.onToolCall(async ({ id, name, args }) => {
  const a = JSON.parse(args || '{}');
  switch (name) {
    // —— 通用动词(玩家说"暂停/调大音量/去大厅/把提示关掉/指一下弃牌键")——
    case 'pause':                 // invoke_action({action:'pause'}) → 已拆包成 name:'pause'
    case 'resume': name === 'pause' ? table.pause() : table.resume(); break;
    case 'set_feature':           // { feature, on:boolean(已归一化) }
      if (a.feature === 'hints') ui.setHints(a.on);
      if (a.feature === 'odds')  ui.setOdds(a.on);
      break;
    case 'set_value':             // { name, value }
      if (a.name === 'volume')     audio.setVolume(Number(a.value));
      if (a.name === 'difficulty') ai.setDifficulty(a.value);
      break;
    case 'navigate':  router.go(a.to); break;          // 'lobby' | 'settings' | ...
    case 'highlight': ui.highlight(a.target); break;   // 'fold' | 'raise' | ...

    // —— 你声明的德州专用动作 ——
    case 'poker_action':
      // ⚠ 涉及筹码:建议你这里弹一个轻确认再执行,而不是直接替玩家出牌
      const okToPlay = await ui.confirmMove(a.move, a.amount);
      if (okToPlay) table.act(a.move, a.amount);
      await companion.sendToolResult(id, { ok: okToPlay, result: okToPlay ? 'done' : 'cancelled' });
      return;
  }
  await companion.sendToolResult(id, { ok: true });   // 别忘了回报,语音里它会据此应一句
});

要点:

• 一定要 sendToolResult,否则语音模型会干等到超时。
• set_feature.on 一律是布尔值(SDK 已把 EL 的字符串归一化)。
• 良性操作(暂停/开关/导航/高亮)即时执行;花钱/出牌类强烈建议你自己再确认一次。

3. 通用动词 ↔ 你的功能(德州对照表)

4. ⭐ 推荐的 appContext 提示词(让伴侣主动用这些工具)

把下面这段作为 appContext.description 传进 createCompanion。它会进入伴侣的 对话上下文,让它知道"我在德州牌桌上、我可以做这些事",从而在合适时机主动调用工具:

你正陪玩家玩《Agent Poker Club》——一桌 6 人(对手是 AI)的德州扑克。请像懂牌的朋友一样
实时解说牌局(轮到玩家、翻牌/转牌/河牌、关键决策、输赢时出声),语气轻松、简短。

你可以在玩家开口时直接在游戏里帮他操作,主动、自然地使用这些工具,不要只用嘴说:
- 暂停/继续牌局 → invoke_action(action:"pause"/"resume")
- 开关发牌提示、赔率显示 → set_feature(feature:"hints"/"odds", on)
- 调整音量、AI 难度 → set_value(name:"volume"/"difficulty", value)
- 切到大厅/设置 → navigate(to:"lobby"/"settings")
- 玩家找不到按钮时,高亮它 → highlight(target:"fold"/"raise"/…)
当玩家明确要求你替他做出牌动作(盖牌/跟注/加注)时,可调用 poker_action;但这涉及筹码,
执行前游戏会让玩家确认,你只需说一句你在帮他操作,不要假装已经完成。

牌局状态会通过实时事件喂给你(底牌、盲注、筹码、每条街、对手动作、输赢)——据此解说和反应。
保持陪伴感:替玩家高兴、调侃、打气,而不是念数据。

这就是"提示词":写得越具体,伴侣越会主动在对的时机调用工具,而不是只用语音说。

5. 还有两件已经做好的(无需额外接)

• 记忆:语音通话结束时调 call.close()(SDK ≥0.5.0 会自动把本局经历提炼进记忆)。 玩家回 Pouchy 主 App 问"刚才德州打得怎样",伴侣会记得。非语音会话用 companion.endSession()。
• 真实头像:const { vrmUrl, imageUrl, name } = await companion.getAvatar(), imageUrl 可直接 <img src>。Pouchy 官方图标:companion.brandIconUrl(512)。

牌局状态(陪玩感)怎么推:见 companion-voice-integration.md 第四节的 world-state 配方。