跳转到内容
Qialike
首页文档

Windows 与 WSL

在 Windows / WSL2 上安装与使用 qialike 的建议、沙箱行为与路径注意点。

qialike 支持 Windows 原生，也支持 WSL2——两者任选。Windows 原生用的是 harness 的 ACL restricted-token runner（与 Linux 的 bubblewrap/Landlock、macOS 的 Seatbelt 同级）；WSL2 则获得 Linux 那两档。本文先给 WSL2 的做法，再说明 Windows 原生的差异。

在 WSL2 中使用

安装

在管理员 PowerShell 中：

Terminal window
wsl --install -d Ubuntu

重启后进入 Ubuntu，按 安装 的说明执行：

Terminal window
curl -fsSL https://qialike.cn/install | bash

WSL2 与 Windows 原生的沙箱对照

两个环境都有内核级隔离，只是走不同的 runner：

环境内核级沙箱
Windows 原生✅ ACL restricted-token runner（开箱即用）
WSL2（Ubuntu 等）✅ bubblewrap，没有则 Landlock（需安装 bubblewrap 或内核 ≥5.13 启用该 LSM）

Windows 原生那档需要单文件构建自带两样东西：它依赖的原生 koffi（由 apps/tui-bin/stub/koffi.js 顶替），以及 runner 进程本身（harness 用模块 specifier 定位它，编译后的二进制答不了，于是 qialike 把 harness 自己的 runner 一并携带并充当其 launcher，见 apps/tui-bin/src/windows-acl-shim.ts）。permission（presets）行在所有平台都已启用。

在 WSL 里装好 bubblewrap 就能拿到最稳妥的那档：

Terminal window
sudo apt update && sudo apt install -y bubblewrap
cat /proc/sys/kernel/unprivileged_userns_clone    # 期望 1

详见 沙箱与权限。

终端选择

qialike 是全屏 TUI，需要一款支持备用屏幕缓冲与真彩色的现代终端：

  • Windows Terminal（推荐）—— Windows 原生与 WSL 都可用。Windows 上请用它，而不是直接启动 cmd.exe / powershell.exe 得到的旧控制台窗口：那是两种东西，cmd.exe / PowerShell 是 shell（解释命令），Windows Terminal 是终端（负责画界面），旧窗口在真彩、鼠标、光标形状与 emoji 回退上都明显更差。Windows 11 已自带，Windows 10 用 winget install Microsoft.WindowsTerminal 安装。详见 安装 → Windows Terminal。
  • WezTerm、Alacritty —— 跨平台，Windows 原生体验较好。
  • WSL2 里也可以直接用发行版自带的终端配置，但从 Windows 侧连入时仍然经由 Windows Terminal。

若颜色偏灰，多半是终端未导出 COLORTERM：

Terminal window
export COLORTERM=truecolor

或只对这一次运行生效：QIALIKE_COLOR=24bit qialike。见 故障排除。

路径与换行

在 WSL 与 Windows 之间跨文件系统工作时注意：

  • 性能：项目放在 Windows 盘（/mnt/c/...）时，9p / drvfs 的 IO 明显慢于 WSL 原生文件系统（~/...）。需要跑大量文件操作时，把工作区放在 ~/projects 之类的位置。
  • 换行：Windows 侧文件常是 CRLF。qialike 把粘贴的文本按内容处理时会归一化换行（\r\n / \r → \n）；但仓库里的脚本若以 CRLF 保存，在 WSL 中执行 bash script.sh 可能报 \r: command not found。用 dos2unix 或 .gitattributes 处理。
  • 权限与行尾：Windows 文件系统不保留 POSIX 权限位与可执行位。在 /mnt/c 下的脚本可能需要在 WSL 里 chmod +x 后用 bash script.sh 显式执行。
  • 符号链接：跨 /mnt/c 的符号链接行为受 Windows 开发者模式与挂载选项影响，建议把需要符号链接的仓库放在 WSL 原生文件系统内。

剪贴板与键盘

  • WSL 里：对话框内的 Shift + 右键 粘贴走 Linux 的剪贴板工具——装 wl-clipboard（Wayland）或 xclip / xsel（X11）。在 WSLg 下通常 X11 工具最省事：sudo apt install xclip。
  • Windows 原生：qialike 通过 powershell.exe -Command Get-Clipboard -Raw 读取剪贴板，无需额外安装任何工具。
  • 键位：Windows Terminal 能正确透传 Alt+Enter（换行）、方向键、PgUp/PgDn 与 Home/End。若某个终端吞掉了 Ctrl+T，用 Alt+T 回退来循环切换推理强度。

Windows 原生的行为差异

Windows 原生可以正常使用：

  • 安装：Windows 原生环境里没有 bash，所以 curl | bash 那条安装命令用不了。两条途径：npm（npm i -g @qialike/cli，需要 Node.js ≥ 18；这条渠道也能自动更新、并且用 npm uninstall -g @qialike/cli 卸载）与手动解压（从 Releases（镜像 gitcode.com/qialike/qialike/releases）下载 qialike-windows-x64.zip，ARM 设备选 -arm64，解压得到单个 qialike.exe，放进 %USERPROFILE%\.dsh\bin\——安装器的默认目录；放别处也能用，只要自己记得位置）。注意 qialike uninstall 保留 bin\ 与其中的 exe——Windows 上运行中的可执行体删不掉——它会打印手动删除命令，见 卸载。两条途径的完整步骤见 安装 → Windows Terminal。

  • 加入 PATH：手动解压的那条要把目录加到用户 PATH，然后重开终端：

    Terminal window
    [Environment]::SetEnvironmentVariable('Path',
      "$env:USERPROFILE\.dsh\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')

    校验：qialike --version。完整步骤见 安装 → Windows Terminal。

  • 沙箱：由 ACL restricted-token runner 提供内核级隔离；workspace-write / read-only 的文件效应同时受纯 JS 栅栏与审批边界约束。

  • 更新：手动解压的副本只能手动更新——运行中的 .exe 无法被替换，安装器也是 bash。qialike upgrade --check 只检查并打印下载链接，更新方式即下载新 .zip、退出 qialike、替换 qialike.exe。npm 装的副本能自动更新（补丁版静默装，与 Linux / macOS 同规则），qialike upgrade 会直接交给 npm。见 更新 → 按安装方式更新。

  • qialike web 在 Windows 上使用 npm 的 .cmd / .bat shim 解析 dsh，因此会用 shell 执行；POSIX 上不会。

无头 / 远程访问

想在 WSL 或远程 Linux 上跑服务、由另一台机器的浏览器访问：保持默认回环绑定，从有浏览器的那台 机器做 SSH 隧道。--host 0.0.0.0 不可用——web profile 会直接拒绝：

error: --host 0.0.0.0 is intentionally not supported yet for safety: it would expose remote
code execution to the network; use 127.0.0.1 instead
Terminal window
# 服务端（WSL 或远程 Linux；无本地浏览器故加 --no-open）
qialike web --no-open                  # 记下打印出的 http://127.0.0.1:3080/?token=… 这条 URL


# 有浏览器的机器上
ssh -L 3080:localhost:3080 user@host
# 然后打开上面那条打印出来的 URL

必须用启动时打印的那条 URL（它带着本次运行的认证 token）：不带 token 访问只会看到 401 dsh web authentication required; reopen the URL printed by dsh web.；认证 cookie 只对签发时 的 authority 有效（127.0.0.1:3080 与 localhost:3080 是两个不同的 authority），所以选定一个 主机名后别再换。--port <n> 可换端口；若端口已被占用，第二个服务会以 EADDRINUSE 退出，而浏览器 仍在跟旧的那个服务说话——它的 token 你并没有。仅建议在可信网络 / 内网 / VPN 下使用。

下一步