pipa-huddle-beta

Pipa Huddle Beta

与用户当前使用的 Agent 发起语音讨论，让他们可以通过口述讨论工作。

输出目标：启动托管语音桥接，清晰说明上下文和保留策略，并可选择生成简洁的后续交接内容。

沟通风格约定：如果存在 ~/.pipa/communication-style.md，则遵循其中的要求；否则，如果 skills/pipa/references/communication-style.md 可用，则遵循其中的要求。表达偏好绝不能覆盖此技能的工作流、输出约定、隐私规则或启动门槛。

工作流

执行前，复制此检查清单，并在工作笔记中持续更新：

Voice Session Progress
- [ ] Step 1 complete: intent and voice-session scope confirmed
- [ ] Step 2 complete: available agent context and session limits stated
- [ ] Step 3 complete: local OpenCode voice bridge availability checked
- [ ] Step 4 complete: browser voice session started or blocker returned
- [ ] Step 5 complete: session notes synthesized without treating raw transcript as durable state
- [ ] Step 6 complete: optional handoff produced when the user wants to continue execution

步骤 1：确认意图

当用户要求通过语音与 Pipa 或当前 Agent 交谈时，使用此技能，包括从另一个浏览器发起的托管会话或中继会话。音频文件交由 pipa-audio-brief 处理；人工视频会议转交其他工具；实时语音编程或口头审批则应明确指出范围限制。

步骤 2：说明会话约定

遵循 references/session-contract.md。

在会话开始时，说明：

• 当前可用的 Agent／上下文
• 语音会话目前能做什么
• V1 目前不能做什么
• 原始音频／转录内容是临时处理还是会保存

不要暗示语音模式是独立的 Agent 大脑。语音会话是在当前 Agent 上下文之上的交互层。

步骤 3：启动本地 OpenCode 语音桥接

遵循 references/transport-prototype.md、references/hosted-relay.md、references/template-contract.md 和 references/privacy-and-retention.md。

桥接会在第一次语音／文本轮次时为本次讨论创建专用 OpenCode 会话，从 opencode run --format json 中获取新会话 ID，并在讨论剩余期间使用 --session <id> 重用该会话。这可以避免通过 opencode session list 猜测会话 ID，也能避免将语音轮次关联到不相关的已有会话。

启动前，仅当启动线程包含可供讨论延续的实质性对话上下文时，才合成精简的内联上下文。上下文应类似：“你现在正在进行一场延续与用户对话的讨论。以下是之前的对话上下文。”然后只包含有用的对话上下文：用户正在讨论的内容、相关决策／偏好、未决问题，以及理解该讨论所需的文件或代码仓库详情。

不要加入“当前目标”来说明要启动讨论。除非与用户之前的对话具体相关，否则不要加入通用代码仓库上下文、会话范围或“不要假设”之类的模板内容。不要加入用户启动讨论的请求、本技能的执行步骤、守护进程／桥接详情、URL、模型／运行时详情或会话创建机制。如果除“启动讨论”外没有实质性的先前对话，则不要传递上下文。

上下文有用时，通过 PIPA_VOICE_SESSION_CONTEXT 内联传递。桥接只会将此上下文注入讨论的第一轮，因此专用讨论会话可以在了解背景的情况下启动，同时不会延续调用者的会话。常规工作流中不要创建或更新启动上下文文件。

使用 --model <current-opencode-model> 将当前 OpenCode 模型传入桥接，以便讨论使用与启动会话相同的模型。不要依赖 OpenCode 默认值，也不要在技能中硬编码特定提供商的模型；应使用当前 Agent 会话的模型 ID。如果当前运行时提供 OPENCODE_MODEL，桥接也会遵循该变量，但优先显式传入 --model，因为这样更容易检查守护进程和托管启动。

对于沙盒或远程浏览器场景，使用受管托管中继路径。生产中继为 https://voice.usepipa.com；每次启动都会在 /s/<session-id> 下创建独立的会话 URL，并与本地桥接守护进程配对，由该守护进程向外连接到 /ws/<session-id>。 将打包的同机桥接服务 skills/pipa-huddle-beta/scripts/start-voice-session.mjs 用作本地回退方案和开发路径。它会提供 localhost 浏览器 UI，使用浏览器 API 捕获语音，将每轮对话发送给 opencode run，并通过浏览器语音合成功能朗读 OpenCode 的回复。

始终通过托管守护进程 JSON 路径启动。桥接服务是一个长期运行的 HTTP/WebSocket 进程，因此不得与 shell 或工具调用的生命周期绑定。新的托管启动只会停止此前记录在 .pipa/voice-session/bridge.pid 中的项目本地 Pipa Huddle 桥接服务，将新元数据写入 .pipa/voice-session/session.json，并在 huddle 会话结束时退出。

本地桥接服务提供 references/template-contract.md 中定义的确定性 huddle 模板。默认情况下，它会呈现技能本地文件 templates/huddle.html；仅在明确进行模板实验时，才设置 PIPA_VOICE_SESSION_TEMPLATE=/absolute/path/to/index.html。

从仓库根目录启动托管模式的默认命令：

node skills/pipa-huddle-beta/scripts/start-voice-session.mjs --daemon --print-url-json --model <current-opencode-model>

如果有需要交接的重要先前对话内容，仅在此次启动时将其内联传入：

PIPA_VOICE_SESSION_CONTEXT='<prior conversation context>' node skills/pipa-huddle-beta/scripts/start-voice-session.mjs --daemon --print-url-json --model <current-opencode-model>

本地回退方案：

node skills/pipa-huddle-beta/scripts/start-voice-session.mjs --daemon --print-url-json --local --model <current-opencode-model>

托管模式应创建中继会话，连接本地桥接守护进程，并打印包含浏览器 URL、守护进程 pid、日志路径和停止命令的 JSON 事件。托管模式默认不会添加 OpenCode 标志。它会将用户的语音或文本轮次转发给本地 OpenCode 桥接服务；OpenCode 仍遵循其常规会话和权限行为。

默认不要继续调用方的线程。huddle 是一个独立会话：它会在第一轮对话时创建新的 OpenCode 会话，之后通过 --session <id> 将所有 huddle 轮次保留在该会话中。仅使用 --huddle-session <id> 恢复现有 huddle 会话；仅在手动调试时使用 --allow-latest-session。

如果桥接服务无法启动，请明确阻止操作。未经检查，不要声称浏览器 STT、Daily/WebRTC 或其他提供方可用。

第 4 步：运行语音会话

会话期间：

• 由于输出使用浏览器语音，每轮对话都要极其简短、自然
• 默认将语音回复控制在 1-2 个短句内
• 除非用户明确要求详细说明，否则避免使用项目符号、编号列表、标题、Markdown 格式和冗长解释
• 用户的意图模糊或前后矛盾时，提出澄清问题
• 跟踪有用的上下文、决定、偏好、阻碍因素和待解决的问题
• 将冗长散漫的语音视为探索性输入；除非用户确认，否则不要将其视为最终指令
• 默认避免存储原始转录文本或音频

允许将文本输入作为调试或无障碍输入方式，但 Agent 回复必须来自 OpenCode，否则就返回阻碍说明。

第 5 步：可选的上下文交接

仅当会话结束时用户有执行意图，或用户要求在 Agent 中继续时，才遵循 references/context-handoff.md。

第 6 步：返回状态或阻碍说明

顺利完成时的最终回复：

Ready to join the huddle: `<session URL>`

受阻时的最终回复：

Voice session blocked.

- **Blocked at:** <transport|microphone|privacy|scope>
- **Why:** <specific blocker>
- **Next:** <minimum action needed>

参考资料

• references/session-contract.md
• references/context-handoff.md
• references/transport-prototype.md
• references/hosted-relay.md
• references/template-contract.md
• references/privacy-and-retention.md