第 03 章

TUI 与输入模式

学会和 Qoder CLI 对话的五种姿势

选对输入符号，你的意图能被 AI 一秒读懂

装好了 Qoder CLI，面对一个终端光标，不知道说什么、怎么选模式。这一章让你和它高效沟通。

怎么开口

装好了，面对一个终端光标，不知道说什么、怎么说

直接打字还是先敲命令？

启动后看到一个输入框，不确定是像聊天一样直接说话，还是要先输入什么指令。

怎么执行 shell 命令？

想让 CLI 帮你跑 git status，但不知道是让它代跑，还是自己切出去敲。

多行需求怎么输入？

需求比较长，回车就发送了，没法换行写清楚——容易表达不完整。

本章的答案：Qoder CLI 用五种输入符号解决了这些问题——你用哪个符号开头，就告诉了 CLI 你这一句话的"性质"。这是它比聊天框更高效的关键设计。

TUI 是什么

先理解你正 staring 的这个界面

TUI（Text User Interface，文本用户界面）是 Qoder CLI 的默认交互模式。它不是冷冰冰的命令行，而是一个用文字画出来的、可以对话的界面——有输入框、有输出区、有状态栏。

说白了，它就像一个住在终端里的聊天窗口，但这个窗口能直接读写你的文件、执行你的命令。

$ cd ~/projects/my-app
$ qodercli
（进入 TUI 界面，出现输入框）
启动位置很重要：在哪个目录启动 qodercli，那个目录就是它的工作区（workspace）。CLI 默认只能读写这个目录里的文件——这是安全设计。换项目就换目录重新启动。

第一个任务

什么都不用学，先跑通一次最简单的对话

启动 TUI 后，直接打字就行——不用敲任何符号。这是最基础的"对话模式"。

> 这个项目是做什么的？简单介绍一下

（CLI 读取 README 和项目结构，给出介绍）

看到 AI 能读懂你的项目、给出回答，就说明环境完全就绪。这就是对话模式的全部用法——和聊天框一模一样。

关键认知：对话模式（>）是默认模式，不需要真的输入 > 符号。它只是文档里用来表示"你在对话模式"的标记。其他四种模式才需要你主动输入对应符号切换。

五种模式

一个符号，决定你这句话的性质

\ + 回车
符号模式用来干什么
>对话模式默认，和 AI 自然对话
!Bash 模式直接运行 shell 命令
/斜杠模式调用内置功能命令
#记忆模式把内容写进项目记忆文件
多行输入输入跨多行的长内容
记忆诀窍：把符号想象成"语气"——! 是命令（你直接下令），/ 是请求（你点菜单），# 是备忘（你做笔记），\ 是换气（你要说很长）。

Bash 模式

在对话里直接敲 shell 命令，不用切终端

在对话模式下输入 ! 开头，这条命令会直接执行，结果留在当前会话里。AI 还能看到这个结果，作为后续对话的上下文。

! git status

（直接执行，输出工作区状态）
On branch main
Changes not staged for commit:
  modified:   src/app.ts

这比"切到另一个终端跑命令、再把结果复制回来"高效得多——命令的输出会自动成为 AI 的上下文。

什么时候用它

  • 想快速看个状态（git、文件列表）
  • 跑个命令让 AI 看结果分析
  • 不想打断和 AI 的对话节奏

什么时候不用

  • 危险命令（rm、强推）——交给 AI 判断更安全
  • 需要 AI 帮你设计命令——直接对话模式问它

斜杠模式

调用 CLI 的内置功能，像点菜单一样

输入 / 开头，会看到所有内置命令。这些命令不是给 AI 的提示词，而是给 CLI 程序本身的指令——执行固定功能。

/status    # 查看 CLI 状态：版本、模型、账号、连通性
/help      # 显示完整帮助
/clear     # 清空当前会话历史，重新开始
/usage     # 看 Credits 消耗
/quit      # 退出 TUI

斜杠命令是确定性的——输入 /status 永远是查看状态，不会有歧义。这和对话模式的"自由发挥"完全不同。

下一章会逐一讲解所有斜杠命令。本章你只需要知道：想用 CLI 的内置功能，就用 / 开头。

记忆模式

用 # 把一句话永久写进项目记忆

输入 # 开头，这句话会被追加到项目的 AGENTS.md 记忆文件。以后每次在这个项目启动 CLI，AI 都会读到它。

# 本项目用 pnpm，不要用 npm 或 yarn

（写入 AGENTS.md，后续会话自动遵守）

这解决了一个高频痛点：你不想每次都重复"我们用 pnpm""测试用 vitest""提交前要跑 lint"——说一次，记住一辈子。

记忆模式 vs 对话模式的区别：对话模式说的话，AI 只在当前会话记得，关掉就忘；记忆模式（#）说的话，AI 在所有未来会话都记得。第 05 章会深入讲记忆系统。

多行输入

需求很长时，用 \ + 回车换行

有时候你要描述的需求很长，或要粘贴一段代码、一段报错。直接回车会被当成"发送"。这时候先输入 \ 再按回车：

> 帮我重构这个函数 \
需求：把同步逻辑改成 Promise \
约束：保持函数签名不变 \
错误处理：用 try/catch 包裹 \
（输入完成后，空行回车发送）

进入多行模式后，连续按两次回车（或输入空行后回车）才会真正发送。中间的换行都只是格式。

何时用多行：粘贴长报错堆栈、贴大段代码让 AI 分析、写结构化的多步骤需求。短需求不用麻烦，直接对话模式一句话发送。

组合实战

一次完整的排查流程，四种模式轮番上阵

假设你在排查一个测试失败。看看五种模式怎么配合：

! npm test                    # Bash 模式：先跑测试看结果

> 这个报错可能是什么原因？    # 对话模式：让 AI 分析

> 帮我修复，但先解释方案       # 对话模式：让 AI 改并说明

# 测试用 vitest，运行用 npx vitest run   # 记忆模式：记住项目测试方式

/help                         # 斜杠模式：忘了某个命令怎么用
真实工作流就是这样：你不会只用一种模式，而是根据"这一刻我要干什么"切换符号。熟练之后，这个切换是下意识的——符号就是意图的快捷方式。

排错指南

新手在输入模式上的常见困惑

对话模式要不要输入 >

不要。> 只是文档标记。直接打字就行。

Bash 命令没执行反而被 AI 解读

原因：忘了用 ! 开头，被当成对话内容了。修复：Bash 命令必须 ! 开头。

斜杠命令报 not found

原因：命令名拼错，或该命令在当前版本不存在。修复：输入 / 看补全列表，从列表里选。

多行输入卡住发不出去

原因：多行模式需要空行 + 回车才发送。修复：多按一次回车，或按 ESC 取消重来。

动手练习

在真实项目里把五种模式各试一遍

练习 1：四种输入各一次

  • 对话模式：问 AI 这个项目用什么框架
  • Bash 模式：! git log --oneline -5 看最近提交
  • 斜杠模式：/status 查看当前状态
  • 记忆模式：# 记住：本项目代码注释统一用中文

练习 2：多行输入

  • 用 \ + 回车，输入一个三行的需求
  • 确认能正确发送并被 AI 理解
做完这个练习，你已经掌握了和 Qoder CLI 沟通的全部基本姿势。从这里开始，所有的进阶能力都建立在"你会用这五种模式"之上。

提前尝鲜：Quest 模式

从"一步步问 AI"进阶到"把任务整体交给 AI"

目前你学的所有模式都是对话式的：你说一句，AI 做一步，你再确认。这很好，但有些任务（比如"加一个完整的用户注册流程"）有十几个步骤，每次确认太累。

Qoder CLI 提供了一个更高级的模式 —— Quest 模式：你给一段清晰的需求文档（Spec），AI 自己规划步骤、执行、跑测试验证、修问题，最后只把结果交给你。

/quest 给 ./src/auth 加上邮箱 + 密码登录，包含：
  - 登录 / 注册 / 找回密码三个 API
  - 前端表单组件 + 校验
  - 单元测试覆盖 > 80%
  - 遵循项目的错误处理规范（见 AGENTS.md）
这个模式将在第 12 章深入讲解。这里先尝个鲜：记住"给一份 Spec → AI 自主完成 → 你 review 结果"这个流程，后面的学习都在为它打基础。

本章回顾

带走的三个核心认知

TUI 是对话界面

启动后直接打字就是对话模式，工作区由启动目录决定。

符号即意图

! 执行、/ 调功能、# 记忆、\ 换行——一个符号说清性质。

真实工作流是组合

根据"此刻要干什么"切换符号，熟练后是下意识动作。

核心结论：Qoder CLI 的五种输入模式，本质是把"你说的话"按用途分流——执行归执行、记忆归记忆、对话归对话。这种分流让 AI 更懂你，也让你更省心。

下一章，我们逐一拆解斜杠命令和内置工具，把 CLI 的"功能菜单"完整看一遍。

延伸阅读

继续本课程

官方资源