# Codex 电视对话试用

这是 main 分支默认关闭的实验功能，尚未包含在 v0.3.0 正式安装包。用户在「设置 → 实验性功能 → Codex 对话 → 开启」后，首页才显示入口。已有旧配对不会自动启用；开关状态独立保存。桌面的「Codex」入口连接同一局域网内电脑上的 Codex CLI；电脑保持开机、联网且连接服务运行时，电视可以输入问题、查看流式回答、停止回答和开始新对话。

当前只做文字对话，没有接入个人文件、日程、米家、其他 Codex 会话，也不能控制电脑或家电。接入这些能力需要单独设计权限与交互。它使用电脑已经登录的 Codex 账号和相应额度，不代表免费、不限量，也不是在电视本地运行模型。

需要 AI 帮忙配置其他电脑或安卓设备时，先读 [AI 适配与引导指南](AI-SETUP.md)。

## 电脑端

需要 Python 3.11 或更新版本、已登录的 Codex CLI，以及生成证书用的 OpenSSL。电脑需要能正常访问 Codex。先运行 `codex login status` 确认登录；未登录时运行 `codex login`。

从项目根目录执行，替换 `192.168.1.20` 为电脑的实际局域网 IPv4 地址：

```sh
python3 companion/server.py --home "$HOME/.guizang-tv" --init --host 192.168.1.20
python3 companion/server.py --home "$HOME/.guizang-tv"
```

第一次生成独立 HTTPS 证书、随机配对令牌，以及 `$HOME/.guizang-tv/tv-pairing.txt`。这个文件相当于电视连接凭证，不要上传、截图分享或放进公开仓库。目录必须放在源码仓库之外。初始化不会覆盖已有配置。

服务默认使用 8765 端口，只绑定初始化时填写的 IP；家庭路由器不需要端口转发。电脑换了 IP、证书过期或需要撤销旧配对时，停止旧服务，换一个私有目录重新初始化并在电视重新配对。试用版没有自动开机常驻设置，关闭终端或电脑睡眠可能导致断开。Ctrl+C 停止服务。

## 电视端

1. 在「设置 → 实验性功能 → Codex 对话」选择「开启」，返回首页。
2. 打开桌面上的「Codex」。对话以首页底部浮层展开，不启动新的 Activity；首次进入先填写连接信息。
3. 用可信的键盘或调试工具，将 `tv-pairing.txt` 的完整内容填入配对框，选择「连接」。当前版本是开发者试用，尚未提供扫码配对。
4. 配对后打开浮层会自动唤起现有系统输入法；看到「已连接」后输入问题。收起键盘、核对内容，再选择输入条右侧的向上箭头发送。也可以连接蓝牙键盘。
5. 发送后及重新进入面板时显示最新消息；停留在底部时随回答更新滚动，主动向上阅读历史时保留当前位置。回答中可以选择「停止」，上下移动到回答区域后可滚动阅读。「新对话」清空面板并为下一次提问创建新上下文。
6. 输入法显示时，返回键先收起键盘；再次返回，或选择「收起」，即可关闭浮层回到桌面。关闭面板停止电视轮询，但已经发送的回答可在电脑端继续完成，再打开可查看结果。

配对设置只存在电视应用私有偏好中；不在 APK 内置地址、令牌或 OpenAI 登录信息。更新安装保留配对，卸载应用会丢失。连接错误不会自动换用未验证的服务。

关闭功能：在同一设置页选择「关闭」，首页入口消失，电视停止后续 Codex 请求，已有配对保留。已经发出的请求可能仍在电脑完成；需要完全停用时在电脑按 Ctrl+C 停止连接服务。关闭不会清除其他桌面设置，也不会自动停止电脑进程。

## 输入浮层的样式与操作

- 桌面上部保持清晰，越向下模糊越强；使用打开瞬间桌面快照的两档高斯模糊渐变叠加，不添加覆盖全屏的统一面板。
- 底部为深色圆角输入条，下沿有缓慢变化的彩色光效。输入法弹出时，浮层随可用窗口高度调整。
- 消息以独立圆角胶囊统一左对齐，短消息按内容收窄，长回复自动换行；自己的消息为白色磨砂底配深色字，回复为黑色磨砂底配浅色字，两者都有细描边和轻微顶部高光。视觉上不显示角色标签，无障碍描述仍区分发送方。
- 上下滚动查看历史；发送和重新打开时定位到最新消息，阅读旧消息时不被流式更新拉走。
- 右侧向上箭头发送，回答过程中变为停止图标；底部提供新对话、连接和收起。
- 光效只在浮层可见且应用活跃时刷新，模糊计算在后台完成并缓存。浮层显示期间背景和时钟快照静止，关闭后恢复实时桌面与壁纸轮播。

样式参考 [Libraries.dev Beam](https://libraries.dev/beam)，并读取其组件和 Voice 示例 CSS，将背景模糊、明暗材质、内侧描边与光效分层适配为 Android Canvas。代码出处、许可和映射见 [Web 到 Android 适配记录](BEAM-ANDROID.md)，没有引入 React/SwiftUI 运行时。其他输入法对窗口高度和返回键的处理可能不同，适配时需实机检查键盘是否挡住输入条。

## 遥控器语音能否直接用？

需要分开验证按键与音频。开源项目 [Key Mapper](https://github.com/keymapperorg/KeyMapper) 和 [TV Key Mapper](https://github.com/kostyay/xiaomi-tv-apps-button-bridge) 提供按键或 Intent 映射，但按键可映射不等于遥控器麦克风可以被第三方使用。

[MiRemote Mapper](https://github.com/81199000/mi-remote-mapper) 和 [mi_remote_control](https://github.com/godarrenw/mi_remote_control) 演示了将兼容遥控器连接到 Mac、通过 ATVV 通道使用麦克风。它们不是现成的国行小米电视语音驱动。把主遥控器改配对到电脑，也会影响原本控制电视的使用方式。

本次国行 HyperOS 实机查询未找到 Android 标准 RecognitionService 或 RECOGNIZE_SPEECH Activity。小爱日志确认语音来源是遥控器 RC，说明原生链路正常，但不能因此声称第三方已获得录音能力。

### 优先使用电视输入法的语音输入

Codex 对话浮层打开后自动唤起电视现有输入法，也可选择输入条左侧的麦克风图标重新打开（无障碍名称为「键盘 / 语音」）。已在本次小米 HyperOS 实机看到搜狗键盘提示“按住遥控器语音键说话”。先打开键盘，再按住语音键说话；松开后按返回收起键盘，核对输入框文字，最后选择面板上的「发送」。仅在 Codex 输入框获得焦点但键盘未打开时按语音键，仍可能进入小爱助手。

输入框请求输入法显示「完成」，并消费输入法的编辑完成事件；即使输入法发出 SEND，也只关闭键盘、聚焦发送按钮，不发出对话请求。发送必须通过面板按钮明确触发。这个入口不需要 ADB 读取语音日志，不更改系统助手和遥控器配对，也不表示应用能直接录制遥控器音频。语音转写服务和数据处理由所用输入法及系统决定，不是本地离线识别。

本次小米 HyperOS 实机已由用户确认语音文字能回填，电视和连接服务也读到了后续测试消息与回答。此结果只适用于本次设备与输入法组合；其他品牌、固件或输入法可能没有这个能力，可使用普通键盘输入。

早期私人实验尝试在短时间内通过 ADB 读取小爱识别结果，用户测试没有回填，已经停用。`--voice-command` 仍是可选的本机实验接口：启动指定本地命令，标准输出作为待确认草稿，最长等待 35 秒。当前浮层没有此接口的触发按钮，日常入口使用系统输入法。不能把来自网络请求的字符串当作命令配置，也不要将早期日志实验视为可用的通用语音驱动。

## 连接与数据边界

- Codex App Server 只通过本机 stdio 与连接服务通信；没有把原始 App Server 或其任意 RPC 暴露给电视。
- 电视固定校验配对证书 SHA-256、有效期及 HTTPS 主机名，再使用独立 Bearer 令牌。禁止明文 HTTP 和重定向，不添加跳过证书校验的开关。
- 服务只提供状态、发消息、停止、新对话和可选语音实验五类请求；拒绝错误令牌、带浏览器 Origin 的请求、过大请求和并发提问。
- 试用关闭 shell、个人配置的 MCP、应用连接器、插件和其他执行入口；线程使用只读沙箱，任何服务端工具审批请求均不获准。不继承用户个人集成作为客厅共享能力。
- 服务不主动写入聊天记录文件，不打印请求内容或凭证。会话使用临时线程，重启连接服务会清空面板上下文；模型服务方仍按其账号及数据政策处理请求。
- 当前仅面向一台可信电视的本地试用，不是互联网部署服务，也没有多用户会话隔离或手机网页客户端。

实现参考：[Codex App Server 官方文档](https://learn.chatgpt.com/docs/app-server)、[配置示例](https://learn.chatgpt.com/docs/config-file/config-sample)、[Android SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)。本机验证 CLI 为 0.163.0-alpha.11，后续版本可能需要适配。

## 开发验证

```sh
python3 -m unittest discover -s companion -v
```

测试覆盖鉴权、浏览器请求拒绝、输入大小与类型、禁止透传任意 RPC、隔离其他线程事件、中断保留部分回答、旧超时不取消新轮次以及断开时拒绝新请求。Android 构建和既有测试仍通过 Gradle 运行。