# 01 Windows 中文输入方案

## 结论（已拍板：方案 C）

主界面是 TUI。启动时检测终端：

- Windows Terminal / VS Code / Cursor 等可用宿主 → 进入自研 TUI
- 经典 cmd（conhost）→ **不进入 Textual**，打印如何用 WT 启动，并 **自动回退 REPL**

不把「在 cmd 里用 Textual 打中文」列为验收。TUI 在 WT 里若中文仍偶发失败，用 `/edit` 外开编辑器写长提示。

## 根因

你在 Qoze 的 cmd 里打不了中文，不是没设 UTF-8。

Textual 在 Windows 上走 `WindowsDriver`：`ReadConsoleInputW` + Raw VT + Kitty Keyboard Protocol（`\x1b[>1u`）。应用一旦 raw 读键，控制台宿主无法完成 IME 组字（拼音 → 汉字）。`PYTHONUTF8` 只影响 Python 输出编码，不修复组字。

Qoze 里 [utils/iterm_driver.py](D:\ideaProject\QozeCode-main\utils\iterm_driver.py) 用拦截 Kitty 协议修 iTerm 中文，但从未接到主程序；Windows 侧没有对应处理。安装脚本生成 `qoze.cmd`，更容易落到 conhost。

当前机器是 Windows 10 1903（build 18362）时，conhost / 早期 ConPTY 的 IME 更差。只在 README 写「请用 Windows Terminal」不够，必须启动时探测并降级。

```mermaid
flowchart TD
  keyPress[按键] --> host{谁拥有输入}
  host -->|熟模式 cooked REPL| ime[系统 IME 组字]
  ime --> appStdin[应用读到完整汉字]
  host -->|生模式 raw TUI| skipIme[应用直接吃按键]
  skipIme --> fail[拼音散开或无法上屏]
```

## 业内对照（为何选 C）

| 方案 | 含义 | G-CODE |
|------|------|--------|
| A. 永远 REPL | 输入权归终端，cmd 也能打中文 | 仅作 conhost 回退，不是主界面 |
| B. `/edit` 外开编辑器 | 类似 git commit | TUI 下的第二兜底 |
| C. 检测终端再决定 | Claude Code / Gemini CLI 一类「请用 WT」的工程化 | **已选**：能开 TUI 就开，不能开就回退 |
| D. 自研 Windows Driver 关 Kitty | Qoze 的 iTerm 思路 | TUI 路径建议做，cmd 仍救不了 |
| E/F. Web 窗 / Win32 悬浮输入框 | 浏览器 IME 完美，或极重 | 不做 |

没有银弹。Cursor、Claude Code、Textual 系 TUI 在 Windows 中文输入上至今都有缺口。稳妥做法是：**不在不支持的宿主里硬开 raw TUI**。

## REPL 是什么

Read-Eval-Print Loop：读一行 → 执行 → 打印 → 再等下一行。不进全屏交替缓冲区，IME 归终端。G-CODE 里它不是产品脸，只是逃生口：

```text
gcode> 请总结 README
[think] ...
[tool] read_file README.md
[final] ...
```

主界面仍是 TUI：顶栏、消息气泡、思考区、工具状态、底部输入框。自己写 widget 与样式。

## 探测规则

允许 TUI（满足任一即可，实现时以代码为准并记日志）：

- 环境变量 `WT_SESSION` 存在
- `TERM_PROGRAM` 为 `vscode` 等已知 PTY
- 父进程名为 `WindowsTerminal.exe`

否则视为 conhost：

1. 打印：当前是传统 CMD，中文输入在全屏界面不可用；请用 Windows Terminal 打开本目录后执行 `gcode`
2. 进入 REPL，功能可用（HITL 用 y/N 文本确认）
3. `gcode --ui tui` 在 conhost 上应失败并提示，禁止硬开
4. `gcode --ui repl` 任意终端都可强制熟模式

TUI 启动后仍建议拦截 / 关闭 Kitty 协议（`\x1b[>1u`），降低 WT 下 IME 失败概率。

## 验收

- 在 Windows Terminal 中：`gcode` 进入 TUI，能完成一轮「提问 → 工具 → 回复」
- 在经典 cmd 中：不进入 TUI；有引导文案；REPL 能打中文并完成同一轮任务
- `--ui tui` 在 cmd 中非零退出或明确拒绝，不黑屏假死
- `/edit` 能打开 `%EDITOR%` 或记事本，保存后把内容当作用户输入
- 不验收：cmd 内 Textual 输入框打中文