第 01 章

走近 Qoder CLI

在终端里和 AI 一起把想法变成可运行的软件

命令行不是复古，而是让 AI 真正接管完整工作流的入口

熟悉的困境

你可能已经用过 AI 对话框写代码，但总卡在"最后一公里"

复制粘贴的疲惫

在对话框里写好一段功能，复制到编辑器，发现和现有代码对不上，又回去改一遍。AI 帮你想，但跑起来还得你来搬运。

它看不见你的项目

你问"帮我重构这个函数"，它却不知道你的函数在哪个文件、依赖了什么。因为没有上下文，只能猜。

重复任务无法自动化

每次提交都要手动跑 lint、跑测试、写提交信息。你想让 AI 帮你做，但它没法碰你的终端。

这些困境的共同根源是：AI 被关在一个对话框里，看不到你的代码、碰不到你的终端、进不了你的流程。Qoder CLI 要解决的就是把这三道墙拆掉。

什么是 CLI

先从定义出发，再用大白话拆开它

Qoder CLI 是 Qoder 平台提供的官方命令行客户端——你在终端里输入 qodercli，就能启动一个能读懂你整个项目、能读写文件、能执行命令的 AI 编程伙伴。

说白了，它就像一个坐在你终端里的同事：你说"帮我把登录接口加上错误重试"，它会自己去看代码、改文件、跑测试，然后把结果交给你确认。你不用再复制粘贴，它直接动手。

$ qodercli
> 帮我给 src/auth/login.ts 加上失败重试逻辑，最多重试 3 次
（CLI 自动读取文件 → 修改代码 → 运行测试 → 汇报结果）

它和聊天框 AI 的根本区别：聊天框里的 AI 只能"说"，CLI 里的 AI 能"做"——它能真的打开你的文件、运行你的命令、修改你的代码。

三种形态

同一个 Qoder，三种使用方式，各管一段

Qoder 平台不止有 CLI。理解这三种形态的分工，你才知道什么时候该用哪一个。

Qoder IDE（图形界面）

一个完整的桌面编辑器，像 VS Code 一样边写边看。适合需要可视化、反复查看改动的日常开发。

Qoder CLI（命令行）★

本课程的主角。轻量、启动快（<70ms）、能进脚本和 CI 流水线。适合自动化、批量任务、没有图形界面的服务器环境。

JetBrains 插件

装进 IntelliJ / WebStorm 等 IDE，把 AI 能力带进你熟悉的工作台。适合已经深度使用 JetBrains 全家桶的人。

关键认知：三者不是替代关系，而是互补。同一个 Qoder 账号，你可以白天在 IDE 里写代码，晚上在服务器上用 CLI 跑批量任务，技能和记忆还能跨形态共享。

为什么是命令行

图形界面更直观，但命令行才是自动化的主场

图形界面的天花板

必须有显示环境，服务器上跑不了
每一步都要人去点，没法无人值守
难以嵌入 CI/CD 流水线
不方便批量处理多个项目

命令行的自由度

SSH 到任何服务器都能用，无需界面
一条命令触发，AI 自己跑到结束
写进 GitHub Actions / GitLab CI 即可自动评审
脚本循环调用，批量改造几十个仓库

但命令行也不是银弹：它的学习门槛比图形界面高——你得记命令、读终端输出、理解权限。这正是本课程存在的意义：带你跨过这道门槛。

它能做什么

四类核心能力，覆盖从写代码到交付的完整链路

理解与编辑代码

读取整个项目的文件、搜索代码、定位问题，然后直接修改文件——不是给你建议让你抄，而是真的改好。

执行命令与跑测试

运行 npm test、git status、构建命令，根据输出判断成功还是失败，再决定下一步。

自主完成长任务

用 Quest 模式把一个完整需求委派出去，AI 自己规划、执行、验证、修复，端到端交付。

接入外部系统

通过 MCP 连 GitHub、数据库、浏览器，让 AI 能读 Issue、查数据、操作网页，能力没有边界。

这四类能力的详细玩法，正是后面 13 章要展开的内容。本章只先建立一个全景认知。

三大卖点

官方强调的三个数字，对应三种实战价值

卖点	数据	对你意味着什么
极致轻量	启动 <70ms	随时敲 `qodercli` 就能开始，没有等待负担，像用 `git` 一样自然
自动化优先	日常流程少 60% 手动步骤	把"跑 lint→跑测试→写提交信息"这类固定流程交给 AI，你只做决策
深度嵌入工具链	70% 重复修复自动处理	能从脚本调用、能进 CI、能用 SDK 二次开发，变成你工具链的一环

读这些数字的正确姿势：它们不是让你"少干活"，而是让你把精力从机械操作，转移到真正需要思考的决策上——该改哪里、改得对不对、要不要上线。

一个任务的样子

用"修复一个报错"感受 CLI 的工作节奏

假设你在排查一个线上 bug。传统流程 vs CLI 流程：

传统流程

看日志找到报错堆栈
手动打开相关文件
读代码找原因
想修复方案
手动改代码
手动跑测试
看结果，不对再回头

全程你一个人在搬运。

CLI 流程

把报错堆栈贴给 CLI
CLI 自动读取相关文件
CLI 定位原因并说明
CLI 提出修复方案
你确认 → CLI 改代码
CLI 自动跑测试
失败 → CLI 自己回头修

你只做"确认"这一个动作。

注意：CLI 不会未经你同意就改东西（除非你开启自动模式）。每一步关键操作都会请求确认——它干活，你拍板。

和 IDE 的关系

很多人问：学了 CLI 还要 IDE 吗？

答案是都要，但各司其职。这是新手最常有的误解，值得专门说清。

用 IDE 的场景

需要可视化对比改动、看 diff
反复调试 UI、需要即时预览
团队 code review 时逐行讨论
不熟悉命令行，想循序渐进

用 CLI 的场景

SSH 到服务器排查问题
批量改造多个项目
写进 CI 自动评审 PR
让 AI 端到端跑完长任务

比喻：IDE 是你坐进驾驶舱亲自开，CLI 是你把任务交给自动驾驶。前者给你掌控感，后者给你效率。成熟的工作流是两者搭配。

学习路径

本课程 14 章分五部分，由浅入深

起步篇（01-03）

认识 CLI、装好它、学会五种输入模式，跑通第一个任务。读完能上手。

基础篇（04-05）

掌握斜杠命令和内置工具，用 AGENTS.md 让 AI 记住你的项目。

扩展篇（06-10）

技能、子代理、MCP、钩子、插件——把单个 AI 变成一支专家团队。

控制篇（11-12）

权限系统和 Quest 模式：怎么安全地把活交给 AI。

工程化篇（13-14）

Print 模式、CI/CD 集成、Agent SDK 二次开发，让 CLI 进你的流水线。

建议的读法：新手请按顺序读 01-05，建立扎实基础；有类似工具经验的可以跳到扩展篇。每章都能独立阅读，不必一口气看完。

开始之前

为了顺利跟完这门课，你需要准备什么

必备的前置知识

会用命令行执行基本命令（cd、ls 这类）
知道什么是终端、什么是 shell
有一个自己的代码项目可以用来练手

需要的环境

macOS、Linux 或 Windows（推荐 Windows Terminal）
网络能访问 qoder.com 完成登录
一个 Qoder 账号（下一章会讲怎么注册）

暂时不要求

不需要用过其他 AI 编程工具
不需要会写复杂的 shell 脚本
不需要懂 AI 模型的内部原理

一个常见坑：Windows 用户请用 Windows Terminal 或 PowerShell，不要用老旧的 cmd.exe——后者对交互式 TUI 的支持不好，容易出现显示错乱。

本章回顾

带走的三个核心认知

CLI 的定位

它是能读写文件、执行命令、进入流水线的 AI 编程伙伴，不只是聊天框。

它与 IDE 互补

IDE 给掌控感，CLI 给效率和自动化。成熟工作流是两者搭配。

课程怎么走

五部分 14 章：起步 → 基础 → 扩展 → 控制 → 工程化，循序渐进。

核心结论：命令行 AI 不是给极客的炫技，而是让 AI 真正接管完整工作流的入口。接下来的旅程，从把它装到你的电脑上开始。

下一章，我们用十分钟把 Qoder CLI 装好、登录、验证它真的能用。