Voice Overlay

我们现在有一个“语音小窗口”，它会在两种情况下出现：一种是电脑听到你说了特定的词（比如“你好，电脑”），自己弹出来；另一种是你按住键盘上的一个特别按钮，它才弹出来。这页纸就是要让这两种方式好好合作，不打架。

现在是怎么做的呢？

1. 如果小窗口已经因为“听到特定词”而打开了，这时你又按住了那个特别按钮，那么按钮这次说话的内容，会接着刚才的话后面写，而不是清空重写。小窗口会一直开着，直到你松开按钮。
2. 松开按钮后，如果输入框里有字，就发送出去；如果没字，就关掉小窗口。
3. 如果是“听到特定词”自己弹出来的，它会在你安静不说话后，自动把话发出去。
4. 如果是你按按钮弹出来的，你一松开按钮，它就会立刻把话发出去。

为了让它们合作，大人们已经做了一些事（到2025年12月9日为止）：

1. 每次语音开始（不管是听到特定词还是按按钮），都会有一个独一无二的“号码牌”。只有拿着最新号码牌的消息，小窗口才会处理，旧的号码牌消息会被扔掉，这样就不会乱了。
2. 按按钮时，如果小窗口里已经有字（是听到特定词写下的），新说的话会接在后面。按钮会等一小会儿（最多1.5秒），等电脑把话说完变成完整的字，如果等不到，就用已经有的字。
3. 电脑会把小窗口和提示音的重要事情记在日记里，方便大人们查看。

接下来，大人们打算怎么做呢？ 他们计划搭一个新的积木房子来管理语音：

1. 搭一个总指挥（VoiceSessionCoordinator）：它一次只管理一个“语音任务”。它会告诉任务开始、更新、结束。它只认最新的“号码牌”，旧号码牌的消息它不理。
2. 做一个任务模型（VoiceSession）：就像一张任务卡片，上面写着：号码牌、是谁发起的（听到特定词还是按按钮）、已经写好的字、正在说的字、要不要响提示音、什么时候自动发送、小窗口现在是什么样子（显示、编辑还是正在发送）。
3. 让小窗口听话（Overlay binding）：做一个“任务广播员”（VoiceSessionPublisher），它总是把当前任务告诉小窗口（SwiftUI）。小窗口（VoiceWakeOverlayView）只听广播员的话，不自己乱改东西。你在小窗口上点“发送”或“关闭”，消息会带着号码牌传给总指挥。
4. 统一发送的路径：当任务结束时，如果输入框里没字，就关掉小窗口；如果有字，就播放一个“发送”提示音，把字送出去，然后关掉窗口。按按钮发送没有延迟；听到特定词发送可以等一小会儿。按按钮结束后，会让“听到特定词”功能休息一小会儿，防止它马上又跳出来。
5. 记好日记（Logging）：总指挥会把重要的事，比如“任务开始”、“被按钮接管了”、“收到一部分话”、“话说完啦”、“发送了”、“关闭了”，都记在电脑日记里。

如果小窗口卡住了，怎么检查呢？ 大人们可以打开一个“魔法窗口”（命令行），输入一段特别的指令，就能看到关于小窗口的日记了。指令是： sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact （这就像用一个望远镜，只看叫“ai.openclaw”的房子里，名字里有“voicewake”的日记本，并且只挑重要的事情看，用简单的话告诉你。） 然后要检查是不是只有一个最新的“号码牌”在活动，旧的是不是都被扔掉了。还要确保松开按钮时，一定会正确地说“任务结束”。

如果想换成这个新方法，可以按这些步骤来：

1. 先把“总指挥”、“任务卡片”和“任务广播员”这几个新积木做出来。
2. 让原来管“听到特定词”的积木（VoiceWakeRuntime）改成和总指挥打交道，而不是直接去碰小窗口。
3. 让原来管“按按钮”的积木（VoicePushToTalk）学会接管已有的任务，并在松开按钮时告诉总指挥“任务结束”，还要记得让“听到特定词”功能休息一下。
4. 让小窗口（VoiceWakeOverlayController）只听“任务广播员”的话，不让别的积木直接叫它。
5. 最后，要测试一下新积木房子：任务接管、休息功能、没字就关闭这些情况是不是都工作正常。