跳转到内容
Qialike
首页文档

快速开始

首次运行、hero 首屏、会话与 resume 的语义、工作区、模型选择与前置要求。

本文假设你已经完成 安装，并且 qialike 在 PATH 上。

首次运行

进入你想让代理操作的项目目录，直接运行：

Terminal window
cd ~/my-project
qialike

裸执行 qialike 会开启一个全新会话并显示 hero 首屏（品牌字标 + 提示）。它从不自动续接上一次会话——这是刻意设计：每一次启动都是一张白纸，除非你显式要求恢复。

此时若还没配模型，首屏会提示 No provider yet — use /models to add one，模型标签显示 not set。

qialike 的 hero 首屏：品牌字标与输入卡片，Model 显示 not set，并提示 No provider yet — use /models to add one

真实会话需要一个模型 key。在 TUI 里输入 /models，按 provider 归类选择模型并填入 key：

/models

/models 模型对话框：一级列表按 provider 归类，含 ＋ Add provider · 62 providers 与搜索框

Add provider 列表：按供应商列出，右侧标注 no key 或 endpoint required

为 DeepSeek 输入 API key 的对话框

key 也可以来自 ~/.dsh 下的设置/凭据或工作区里的 .env。

输入你的需求，回车后即可开始任务。

会话与 resume 的语义

命令行为
qialike开启新会话，显示 hero 首屏。从不自动续接。
qialike resume继续当前目录下最近使用过的会话（按最后活动时间排序），直接进入会话界面。
qialike --resume <sessionId>恢复指定持久化会话。

几点需要注意：

  • 恢复某会话或向它发消息，都会把它标记为「最近使用」，状态行会标注 (resumed)。
  • 显式 --resume <sessionId> 始终优先于位置参数 resume。
  • 如果当前目录下还没有任何有内容的会话，qialike resume 仍然进入会话界面，而不是退回 hero 首屏。
  • 会话与目录绑定：resume 与 /sessions 都只列出当前工作目录的会话。

每次启动都自动续接

如果你希望启动就接着上次干，把 resume_last 设为 true：

{
  "resume_last": true
}

文件位置是 ~/.dsh/qialike.json。也可以用环境变量开一次：

Terminal window
QIALIKE_RESUME_LAST=1 qialike

默认值是 false，即每次启动全新开始。环境变量被设置时，它的值也会写回配置文件，因此后续不带变量的启动会沿用。

在工作区中操作

qialike 默认以当前目录为工作区。要指向别处：

Terminal window
qialike --workspace ~/proj

每个工作区拥有自己的会话集合：--workspace ~/proj 之后，resume、/sessions、/new 都围绕 ~/proj 的历史展开。

浏览器 UI 与无头 / 远程访问

qialike web 运行已安装的 dsh CLI，其版本应不低于本 qialike 构建内嵌的 harness 版本：两端读写同一份 ~/.dsh/sessions 日志，更旧的 dsh 读取器会把新版范围压缩的 sourceEventSeqs 误判为损坏历史（SessionPersistenceCorruptionError）。启动前会先核对 dsh：未安装或版本不一致时，告警并打印安装命令（版本不一致时不启动 web、直接退出）。dsh 需在 PATH 上，或用 $QIALIKE_DSH 指向它。

dsh web 绑定 127.0.0.1:3080，启动后打印一条带本次运行认证 token 的 URL（http://127.0.0.1:3080/?token=…）并用默认浏览器打开它。请就用那条 URL：不带 token 访问会得到 401 dsh web authentication required; reopen the URL printed by dsh web.；它种下的认证 cookie 只对签发时的那一个 authority 有效（127.0.0.1:3080 与 localhost:3080 是两个不同的 authority），所以选定一个主机名后别再换。

本机跑服务，别机浏览器访问

服务端保持默认回环绑定（127.0.0.1），从有浏览器的那台机器做 SSH 隧道即可——服务全程不暴露到网络。不要用 --host 0.0.0.0 直接对外提供：web profile 会拒绝（error: --host 0.0.0.0 is intentionally not supported yet …）。隧道做法：

Terminal window
# 无头 / 纯终端主机上（无本地浏览器，故加 --no-open）
qialike web --no-open                  # 记下打印出的 http://127.0.0.1:3080/?token=… 这条 URL


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

本机 3080 也被占用时，只改本地映射即可——服务端不用重启，token URL 也不变：ssh -L 8080:localhost:3080 user@headless-host，再打开 http://127.0.0.1:8080/?token=…。只有服务端 3080 被占用时才需要 qialike web --port <n>，并同步改用新的隧道目标与 URL。

选择模型

输入 /models：

/models

模型列表与自带 key 的配置方式见 模型。

首屏在做什么

启动后你会看到：

  • hero 首屏：全新会话时的欢迎画面，等待你输入第一句话。
  • 对话区：转写区（模型输出、工具行、思考行）加底部输入卡片。
  • 右侧 Steps 面板：终端宽度 ≥110 列时自动显示，可用 /sidebar 或点击其标题栏切换。
  • 终端高度：此界面最小需要 14 行——不足时 qialike 会显示 Terminal too small — keys paused 并忽略所有按键（含 Ctrl+C），把窗口调高即恢复。
  • 状态栏：运行期间显示相位与经过秒数，例如 ⠙ thinking · 12s · Esc to pause；事件静默较久时会标出 Ns since last event。

直接输入自然语言即可开始。以 / 开头会打开斜杠命令面板。

前置要求

内存

编译后的单文件可执行体是 Bun/JSC 运行时。实测（整棵进程树、静置 12 秒）：启动 hero 峰值约 250–290 MB，加载超大转录约 330–345 MB，稳态常驻约 170 MB（hero）–225 MB（长会话）。

建议 ≥1 GB 内存；512 MB 可用但偏紧，低于 512 MB 不受支持。RSS 会随使用缓慢上升后趋于平台，这是 GC 策略而不是泄漏。内存紧张时用：

Terminal window
BUN_JSC_collectContinuously=1 qialike

代价是 GC 更频繁。详见 配置。

Linux 沙箱

受限 bash 优先经 bwrap（bubblewrap）运行，并要求内核开启非特权 user namespace；没有 bubblewrap 时会落到 qialike 自带的 Landlock（需内核启用该 LSM，≥5.13）。两级都不可用时，应用照常启动、非 shell 工具全部可用，但 workspace-write / read-only 下每条 bash 都会 fail-closed 报 SANDBOX_UNAVAILABLE，只有 danger-full-access（无隔离）能跑。

Terminal window
# Debian / Ubuntu
sudo apt install bubblewrap

细节与三档模式的区别见 沙箱与权限。

终端颜色

主题色是 hex，交由 Ink/chalk 输出；chalk 依据环境变量判断终端色深。若你的终端支持 24 位却未导出 COLORTERM，qialike 会落到 256 色档：

Terminal window
export COLORTERM=truecolor
# 或只对这一次运行生效：
QIALIKE_COLOR=24bit qialike

16 色档下深色方案的卡片与页面同为黑——调色板里没有第二个近黑色可选，属设计上的降级，无法修复。

详见 配置 与 故障排除。

下一步