Windows 终端环境

Windows 自带的传统控制台（cmd.exe / conhost）默认字体不含 emoji 与 Nerd Font 图标字形， 也不支持真彩色，所以 zqagent 在这里只能降级显示：✅ 变成 [OK]、表格边框退化为 ASCII、 颜色偏暗淡。功能不受影响，但观感与 Linux / macOS 差一截。

本页给出推荐配置，以及 zqagent 内置的自动引导。

推荐配置

层次	推荐	说明
终端	Windows Terminal	真彩色、GPU 加速、标签页与分屏，可同时承载 cmd / PowerShell / WSL
字体	Nerd Font（等宽）	补全图标字形，如 JetBrainsMono Nerd Font
Shell	PowerShell 7 或 Git Bash	脚本体验更接近 Linux
提示符	oh-my-posh / starship	图标化提示符与 git 状态

1. 安装 Windows Terminal

方式 A（推荐，Win10 1809+ 自带 winget）：

winget install --id Microsoft.WindowsTerminal -e --accept-source-agreements --accept-package-agreements

方式 B：打开「Microsoft Store」，搜索 Windows Terminal 安装。

2. 安装 Nerd Font

winget install --id DEVCOM.JetBrainsMonoNerdFont -e --accept-source-agreements --accept-package-agreements

等价字体任选其一（包名可用 winget search nerd 查）：CaskaydiaCove Nerd Font、 FiraCode Nerd Font、Hack Nerd Font。也可以到 Nerd Fonts 官网 下载，解压后右键字体文件 →「为所有用户安装」。

注意：Nerd Font 不等于普通的 JetBrains Mono。装完要在终端里选带 Nerd Font 后缀的那一款，否则图标仍是方块。

3. 设为默认终端

Windows Terminal → 设置 → 启动 →「默认终端应用程序」→ 选 Windows Terminal。 此后从 cmd.exe / PowerShell 启动的也会进入 Windows Terminal。

4. 在 Windows Terminal 里选中字体

设置 → 配置文件 → 默认值 → 外观 → 字体 → 选 JetBrainsMono Nerd Font。

也可以直接改 settings.json：

{
  "profiles": {
    "defaults": {
      "font": { "face": "JetBrainsMono Nerd Font", "size": 11 }
    }
  }
}

5. 让 shell 更好用（可选）

winget install --id Microsoft.PowerShell -e      # PowerShell 7
winget install --id JanDeDobbeleer.OhMyPosh -e   # oh-my-posh 提示符

zqagent 的行为

• 启动时探测终端能力：不支持 emoji / Unicode 时，自动把自身输出降级为 ASCII 标记 （✅→[OK]、❌→[x]、⚠️→[!]），Markdown 表格也改用 ASCII 边框。
• 检测到传统控制台时会主动引导：先询问是否让 agent 用 winget 自动安装 Windows Terminal 与 Nerd Font（命令逐条走审批）；装不成、或尚未配置 LLM 连接时， 直接打印手动安装教程。
• 相关环境变量：

变量	作用
ZQAGENT_TERM_SETUP=0	关闭启动时的终端环境引导
ZQAGENT_TERM_SETUP=1	强制触发引导（便于预览教程）
ZQAGENT_EMOJI=1/0	强制开启 / 关闭 emoji 与 Unicode 表格
ZQAGENT_ASCII=1	强制降级为 ASCII 标记

故障排查

现象	处理
winget 不存在	在「Microsoft Store」搜索「应用安装程序」(App Installer) 安装，或改用上面的方式 B
图标仍是方块	终端里选的字体不是 Nerd Font 那一款
emoji 仍显示为 ?	确认已在 Windows Terminal 中运行，且 ZQAGENT_EMOJI 未被设为 0
颜色偏暗淡	conhost 不支持真彩色，换用 Windows Terminal 即可

下一步

• CLI 使用
• 内置工具