Qoder

01 学习交流群

知识库之外，我们还建了「主流 Agent 入门交流群」。

进群和大家一起交流主流 Agent 的使用方法、适用场景和入门实践，分享不同工具的上手经验、工作流与真实案例，也会同步专题最新更新和实战资料。

扫码加入，一起找到适合自己的 Agent，真正用起来。

02 学前须知

本教程配套代码素材：https://gitee.com/geektime-geekbang_admin/ai-tutorial-material/tree/master/qoder-materials

03 认识qoder

在动手之前，我们先花几分钟聊聊天，搞清楚一件事：Qoder 到底是个什么东西，它凭什么能帮我们写代码。

我知道你可能已经迫不及待地想敲命令了。但相信我，这一章花的时间，会在后面帮你省下更多的时间——因为只有当你明白手里这件工具「擅长什么、不擅长什么」，你才知道什么时候该把活儿交给它，什么时候该自己盯紧一点。

1.1 先把话说白：Qoder 是什么

一句话概括：Qoder 是一个会写代码的 AI 工程师，就住在你的电脑里。

它不是那种你问一句、它答一句，然后你还得自己把代码复制粘贴回项目的聊天机器人。Qoder 更进一步——它能直接读懂你整个项目，能自己动手改文件、跑命令、看报错、再修正，像一个坐在你旁边、随时能接管键盘的同事。

举个最直观的例子。假设你的程序报了一个错，屏幕上一大片红色的堆栈信息，看得人头皮发麻。传统做法是你自己一行行读、猜哪里出了问题、上网搜。而在 Qoder 里，你可以直接把报错甩给它，说一句「帮我看看这是怎么回事」。它会去读相关的代码文件，定位到真正出问题的那一行，告诉你原因，然后（在你同意之后）把修复写好。

这就是它和普通 AI 聊天最大的区别：它不只给建议，它能真的把事情做完。

1.2 那它具体能帮你做哪些事

我们来把它的能力落到几个你迟早会遇到的场景上：

• 从零写功能。 你描述需求——「我要一个能记录收支的小工具」——它帮你把代码结构搭起来，把第一版功能实现出来。我们这本教程的主线，干的就是这件事。
• 读懂陌生代码。 接手了一个别人写的项目，几百个文件，完全不知道从哪看起？你可以直接问它「登录逻辑在哪」「这个函数被谁调用了」，它会替你翻遍代码库给出答案。
• 调试排错。 前面说的，把报错交给它，它帮你找根因、给修复。
• 重构。 代码能跑，但写得乱、想优化结构？它能在你「有测试兜底」的保护下，安全地帮你整理。
• 写测试。 很多人懒得写测试，Qoder 可以帮你补上，而且写得又快又全。
• 自动化和杂活。 批量改文件、生成文档、跑一系列命令……这些重复劳动，交给它最省心。

你会发现，这些能力有个共同点：它们都发生在「一个真实的项目」里，而不是空中楼阁。 所以我们不打算空讲功能，而是直接上手做一个项目，让你在做中学。

1.3 Qoder 有好几种「长相」，该用哪个

Qoder 不是一种东西，它有几种不同的产品形态，就像同一个人可以穿正装、也可以穿运动服——内核是同一个，但适配的场合不同。搞清楚它们的区别，你就知道自己该穿哪套。

① Qoder CLI —— 住在终端里的 AI（本教程的主角）

这是 Qoder 的命令行形态。你在终端里敲一个 qoder，就把它唤醒了，然后你们在一个项目目录里对话、协作。

它适合谁？

• 习惯泡在终端里的人，敲命令比点鼠标还快；
• 需要连远程服务器干活的人（服务器上通常没有图形界面，CLI 是唯一选择）；
• 想把 AI 嵌进自己现有工作流、甚至写进脚本里自动跑的人。

它的特点是轻、快、灵活，没有花哨的界面，一切都在文字的来回之间完成。这也是为什么我们选它当主角——把 CLI 玩明白了，你对 Qoder 的理解就打通了任督二脉。

② Qoder IDE —— 一个完整的图形化编辑器

这是一个独立的桌面应用，长得像一个代码编辑器：左边是文件树，中间是代码，旁边有一个 AI 对话面板。你能用鼠标点点点，也能看到代码高亮、diff 对比等等。

它适合谁？

• 刚入门、对终端还有点怵的新手；
• 喜欢「所见即所得」、习惯图形界面的人；
• 从零开始一个新项目，想要一个一体化环境的人。

我们会把 Desktop 放到最后一章再介绍。原因是：CLI 是理解 Qoder 的地基，地基打牢了，再回头看图形界面会觉得「哦，原来就是把这些能力换了个壳」，学起来毫不费力。

③ IDE 插件 —— 装进你已有的编辑器里

如果你已经用惯了 VS Code、JetBrains 这类编辑器，一天都不想离开它们，那 Qoder 也提供了插件形态——把 AI 能力直接塞进你熟悉的工具里，不用换环境。

它适合谁？

• 已经有一套顺手的编辑器、不想推倒重来的人；
• 希望在现有项目里「就地」获得 AI 辅助的人。

一张表帮你选：

说句掏心窝的话：这三种形态背后是同一套能力，你不用纠结「选错了怎么办」。我们先用 CLI 把基本功练扎实，等你熟了，无论切到 Desktop 还是插件，都是水到渠成的事。

1.4 我们这本教程怎么学

先跟你交代一下接下来的节奏，让你心里有数：

1. 第 2 章，我们先把 Qoder 装到你的电脑上（无论你用 Mac、Linux 还是 Windows，都有对应步骤）。
2. 从第 3 章开始，我们正式启动实战项目「记账小管家」。 你会先学会用 git 给项目「立规矩」——这是我特别想让你养成的好习惯，它会在你后面写错代码、想反悔的时候救你一命。
3. 第 4 到第 7 章，我们一步步把这个记账工具做出来、修好、优化好、最后交付。每往前一步，你都会顺手学会一个 Qoder 的核心能力。
4. 第 8 章，我们回头看一眼 Qoder Desktop，把三种形态彻底串起来。

关于命令，再啰嗦一句：正文里的命令以 macOS / Linux 为主，遇到 Windows（PowerShell 或 WSL2）不一样的地方，我会用醒目的方式单独标出来。你只需要认准自己系统对应的那一段，照着敲就行，不用被其他系统的命令干扰。

好了，理论部分到此为止，再多说就要变成「说明书」了——那可不是我们的风格。

现在，去把你的 Qoder 装上吧。翻到第 2 章，我们正式开始动手。

04 安装与首次启动

这一章的目标很简单：把 Qoder 装到你的电脑上，并且成功登录。

我知道「安装」这两个字常常让人心里一紧——尤其是对不常碰命令行的人来说，怕出错、怕报错看不懂。别担心，我会把每一步都掰开揉碎讲清楚：在哪打开终端、敲什么、回车后会看到什么、万一报错怎么办。你只要找到自己操作系统对应的那一节，从头照着做就行，其他系统的部分可以直接跳过。

2.1 开始之前：确认你的电脑符合要求

在动手前，先花一分钟确认两件事，能帮你避开绝大多数坑：

• 系统：macOS、Linux、Windows 都支持。如果你用的是 Windows，我强烈建议你后面走 WSL2 那条路（2.5 节会讲为什么），体验会顺滑很多。
• 芯片架构：arm64（比如苹果的 M 系列芯片）或 amd64（大多数 Intel/AMD 电脑）都行，不用特意去查，正常电脑都满足。
• Node.js（可选）：如果你打算用 npm 的方式安装，需要 Node.js 20 或更高版本。不过我们下面用的是官方的一键脚本，不需要你提前装 Node.js，所以你暂时可以忽略这一条。

确认完毕，我们开始。

2.2 macOS 用户看这里

第一步：打开「终端」。

终端就是那个能让你用文字命令电脑的窗口。打开方式有两种，任选其一：

• 按下 Command（⌘）+ 空格键，屏幕中间会弹出一个搜索框（叫 Spotlight），在里面输入 终端 或 Terminal，回车。
• 或者打开「访达（Finder）」，进入「应用程序」→「实用工具」文件夹，双击里面的「终端」。

打开后，你会看到一个窗口，最后一行停在一个闪烁的光标处，前面通常长这样：你的用户名@电脑名 ~ %。这就是在等你下命令了。

第二步：粘贴安装命令并回车。

把下面这一整行复制到终端里，然后按回车：

curl -fsSL https://qoder.com/install | bash

这行命令在干嘛？简单说：curl 是一个「从网上下载东西」的小工具，它把 Qoder 的官方安装脚本从 https://qoder.com/install 下载下来，然后用 |（管道符）把脚本交给 bash 去执行。整个过程是全自动的，你只需要等它跑完。

小提示：往终端里粘贴，用 Command（⌘）+ V。粘贴后记得按回车。

第三步：看它跑完。

回车后，屏幕上会滚动一些文字——那是它在下载、解压、配置。这中间可能会问你一两次问题（比如要不要把命令加到环境变量里），一般情况下照着默认、按回车或输入 y 确认即可。耐心等它停下来，直到光标重新回到闪烁状态。

第四步：验证是否装好。

为了确认安装成功，敲这一行并回车：

qoder --version

如果它回给你一个版本号（比如 qoder 1.x.x 之类），恭喜你，装好了！

如果它说 command not found: qoder（找不到命令），别慌，通常是因为环境变量还没生效。最简单的解决办法是：关掉当前终端窗口，重新开一个，再试一次 qoder --version。 绝大多数情况这样就好了。

装好之后，先别急着用，跳到 2.6 节 完成登录。

2.3 Linux 用户看这里

Linux 上的流程和 macOS 几乎一模一样，因为大家用的都是同一个安装脚本。

第一步：打开终端。

不同桌面环境快捷键略有差别，最通用的是按 Ctrl + Alt + T，通常就能直接弹出终端。如果不行，可以在应用菜单里搜索「Terminal」或「终端」。

第二步：执行安装命令。

curl -fsSL https://qoder.com/install | bash

含义和 macOS 那节讲的一样：下载官方脚本并执行。回车后等它跑完，中间若有确认提问，按默认（回车或 y）即可。

如果报错说找不到 curl：有些精简版 Linux 默认没装 curl。你可以先装它，再回来执行上面的命令。根据你的发行版选一条：

• Debian / Ubuntu 系：

  sudo apt update && sudo apt install -y curl
  

• Fedora / RHEL 系：

  sudo dnf install -y curl
  

（sudo 的意思是「用管理员权限执行」，敲完回车后它可能会让你输入开机密码。注意：输密码时屏幕上不会显示任何字符，这是正常的，盲打完按回车就行。）

第三步：验证。

qoder --version

出现版本号就成功了。若提示 command not found，同样先关掉终端重开一个再试；Linux 上有时需要重新加载配置文件，可以执行 source ~/.bashrc（如果你用的是 zsh，则是 source ~/.zshrc）。

装好后跳到 2.6 节 登录。

2.4 Windows 用户看这里（PowerShell 方式）

Windows 上有两条路可走：一是直接用 PowerShell（这一节），二是用 WSL2（下一节，我更推荐）。如果你只是想快速装好、且主要用命令行，这一节就够了；如果你想要更接近 Linux 的开发体验，可以直接跳到 2.5。

第一步：打开 PowerShell。

• 右键点击屏幕左下角的「开始」按钮（那个 Windows 图标），在弹出的菜单里找到「Windows PowerShell」或「终端（Terminal）」，点它。
• 或者按 Win + R，输入 powershell，回车。

打开后是一个蓝色或黑色的窗口，最后停在类似 PS C:\Users\你的用户名> 的提示符处，等你输入命令。

第二步：执行安装命令。

复制下面这一行，粘贴进 PowerShell（右键即可粘贴），然后回车：

irm https://qoder.com/install.ps1 | iex

这里的 irm 和 iex 是 PowerShell 里的命令简写：irm（Invoke-RestMethod）负责从网上把安装脚本下载下来，iex（Invoke-Expression）负责把它执行掉。作用和 macOS/Linux 那条命令是一样的，只是换成了 PowerShell 的写法。

如果弹出「禁止运行脚本」之类的报错：Windows 出于安全考虑，默认可能不允许运行脚本，报错信息里会出现 Execution Policy（执行策略）字样。解决办法是，先执行下面这行来放开当前用户的限制：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

它会问你是否确认，输入 Y 回车即可。然后再重新执行上面的 irm ... | iex 安装命令。

如果你更习惯用传统的命令提示符（CMD），也可以用这条命令安装：

curl -fsSL https://qoder.com/install.cmd -o install.cmd && install.cmd

第三步：验证。

qoder --version

出现版本号即成功。若提示找不到命令，关掉 PowerShell 重新打开一个再试（让环境变量重新加载）。

装好后跳到 2.6 节 登录。

2.5 Windows 用户看这里（WSL2 方式，推荐）

先解释一句：WSL2 是 Windows 官方提供的「在 Windows 里跑一个真正的 Linux」的功能。 装好它之后，你就相当于在 Windows 电脑上开了一个 Linux 子系统，可以在里面用和 Linux 一模一样的命令。

为什么推荐这条路？因为大量的开发工具、教程、命令都是围绕 Linux/macOS 生态设计的，在 WSL2 里你能获得和它们完全一致的体验，将来遇到各种教程也能直接照抄命令，少踩很多 Windows 特有的坑。

第一步：安装 WSL2。

用管理员身份打开 PowerShell（右键「开始」按钮 → 选择「Windows PowerShell（管理员）」或「终端（管理员）」，如果弹出权限确认，点「是」），然后执行：

wsl --install

这条命令会自动帮你开启所需的功能，并安装一个默认的 Linux 发行版（通常是 Ubuntu）。

第二步：重启电脑。

安装完成后，你需要重启一次电脑，让 WSL2 真正生效。这一步别偷懒，重启是必须的。

第三步：设置 Linux 的用户名和密码。

重启后，通常会自动弹出一个 Ubuntu 的窗口，提示你创建一个用户账号。按提示：

• 先输入一个你想用的用户名（英文小写即可，比如 zhangsan），回车；
• 再输入密码，回车。注意：输密码时屏幕上不会显示任何字符（连星号都没有），这是 Linux 的正常行为，别以为没输进去，盲打完回车就行；
• 它会让你再输一次密码确认。

设置完，你就进入了 Linux 的终端，提示符长这样：你的用户名@电脑名:~$。

第四步：在 WSL2 里安装 Qoder。

从这里开始，你就完全按照 Linux 的方式 来做了。在这个 Ubuntu 终端里执行：

curl -fsSL https://qoder.com/install | bash

如果提示找不到 curl，先装一下：

sudo apt update && sudo apt install -y curl

装好后验证：

qoder --version

出现版本号就成功了。以后每次要用，就打开这个 Ubuntu（WSL）终端即可。

接下来进入 2.6 节 登录。

2.6 首次登录：让 Qoder 认识你

无论你用的是哪个系统，装好之后都要做一次登录，Qoder 才知道「你是谁、可以用它的服务了」。

登录方式很自然：先进入任意一个项目文件夹，然后运行 qoder。

比如，你可以先随便建个练习文件夹（下一章我们会正式建项目，这里只是先跑通登录）：

• macOS / Linux / WSL2：

  mkdir ~/qoder-hello && cd ~/qoder-hello
  qoder
  

• Windows PowerShell：

  mkdir $HOME\qoder-hello; cd $HOME\qoder-hello
  qoder
  

敲下 qoder 回车后，它会在终端里启动，并引导你完成登录——通常是给你一个链接或者一段提示，让你用浏览器授权，或者输入账号信息。你只需要照着屏幕上出现的中文提示，一步一步来即可。因为登录界面可能会随版本更新略有变化，所以我这里不写死每一步，但请放心，它的引导足够清晰，跟着走就能完成。

登录成功后，你就正式拥有了一个随时待命的 AI 工程师。

2.7 日后升级与卸载

软件总要更新。Qoder 升级很简单，两种方式任选：

• 直接用它自带的升级命令：

  qoder update
  

• 或者重新跑一遍安装脚本，加个强制覆盖的参数（macOS / Linux / WSL2）：

  curl -fsSL https://qoder.com/install | bash -s -- --force
  

至于卸载，如果哪天你不需要它了，删除对应的可执行文件和配置目录即可；具体路径可以查阅官方文档，这里就不展开了——毕竟我猜你装上之后就舍不得卸了。

搞定！你现在应该已经能在终端里敲出 qoder --version 并看到版本号，也完成了登录。

是不是没有想象中那么可怕？下一章，我们就正式开始动手做「记账小管家」——而且我会先教你一个特别重要的好习惯：用 git 给项目上「保险」。走，翻到第 3 章。

05 起步与好习惯

终于到动手的时候了。从这一章开始，我们要正式做**「记账小管家」**这个项目。

不过在写第一行代码之前，我想先带你做一件看起来「不着急」、实则能救你无数次命的事——给项目装上 git，立好规矩。

我先把道理讲明白，你就知道为什么我这么坚持了。

3.1 为什么一上来就要讲 git

想象一下这个场景：你跟着教程，让 Qoder 改了一堆代码，本来跑得好好的，结果改完之后程序崩了，怎么都修不好。这时候你最想干什么？——回到改之前的那个版本，对吧？

如果没有 git，你只能干瞪眼，或者凭记忆一点点往回改，改到怀疑人生。而有了 git，你只需要一句话，就能「穿越」回任意一个之前保存过的状态。

git 就是这样一个工具：它帮你在项目的漫长历史里，打下一个又一个「存档点」。 每完成一小步，你就存一次档。万一后面搞砸了，随时能退回上一个存档。玩游戏的人一定秒懂——没人会不打存档就去挑战 Boss。

而且，git 和 Qoder 是天作之合。因为 AI 改代码改得又快又多，有个存档机制在旁边兜底，你才敢放心大胆地让它放手去做。所以这个习惯，我们从第一天就要养成。

放心，git 你只需要会几个最常用的命令就够了，我不会把你带成 git 专家。用到的时候我都会解释。

3.2 建一个项目的家

先来给项目找个「住处」——也就是一个文件夹。

macOS / Linux / WSL2，在终端里执行：

mkdir ~/ledger && cd ~/ledger

Windows PowerShell，执行：

mkdir $HOME\ledger; cd $HOME\ledger

这两条命令做的事情是一样的，只是写法因系统而异：

• mkdir ~/ledger：在你的用户主目录下，新建一个叫 ledger（账本）的文件夹。那个 ~ 符号代表的就是「你的主目录」，是个通用简写。Windows PowerShell 里主目录写作 $HOME。
• cd ~/ledger：进入这个刚建好的文件夹。cd 是「切换目录」的意思。之后我们所有的操作，都在这个文件夹里进行。

小知识：&&（在 macOS/Linux 里）和 ;（在 PowerShell 里）都是「把两条命令连着执行」的意思。前者表示「前一条成功了才执行后一条」，后者表示「依次执行」。你现在不用深究，照抄即可。

执行完之后，你人已经站在了 ledger 文件夹里。可以敲 pwd（macOS/Linux/WSL2）或 pwd（PowerShell 也支持）确认一下当前位置，它会打印出你现在所在的文件夹路径。

3.3 用 git 把这里变成一个「有存档」的项目

现在，把这个文件夹交给 git 来管理。依次执行下面几条命令。

第一步：初始化 git 仓库。

git init -b main

这条命令会在当前文件夹里悄悄建一个隐藏的 .git 目录，从此 git 就开始「盯着」这个项目了。执行后它一般会回一句类似 Initialized empty Git repository in ... 的话，意思是「空仓库已建好」。

第二步：告诉 git 你是谁。

git 每次存档都会记录「是谁存的」，所以要先报上名号：

git config user.name "你的名字"
git config user.email "你的邮箱"

把引号里的内容换成你自己的即可，比如 git config user.name "Zhang San"。这个名字和邮箱只是记录用途，随便填也行，但建议填真实的，将来你会感谢自己。

如果你想让这台电脑上所有项目都用这个身份，可以在两条命令里把 user.name 换成 --global user.name（即 git config --global user.name "..."）。

第三步：创建 .gitignore，告诉 git 哪些东西别管。

有些文件是不该被 git 记录的，比如程序运行时自动生成的临时文件、包含密码的配置、体积巨大的数据文件等等。我们用一个叫 .gitignore 的清单来把它们排除掉。

这一步正好可以让 Qoder 帮你做——不过我们还没正式启动它，所以我先带你手动建一个简单的。用你顺手的文本编辑器，在 ledger 文件夹里新建一个文件，文件名就叫 .gitignore（注意开头有个点），内容先写这些：

# Python 运行时产生的缓存目录
__pycache__/
*.pyc

# 虚拟环境（后面章节可能会用到）
.venv/
venv/

# 存放个人数据的文件，避免误传到网上
*.local

# 操作系统自动生成的杂七杂八的文件
.DS_Store

每一行前面带 # 的是注释，是写给人看的说明，git 会忽略。剩下的每一行就是一种「不要记录」的规则。你现在不用完全理解每条规则，知道「这个文件的作用是列出不该被 git 管理的文件」就够了。

第四步：打下第一个存档点。

git add .
git commit -m "chore: 初始化项目"

解释一下：

• git add .：把当前文件夹里的东西（那个 . 代表「当前目录的全部内容」）都放进「待存档区」。
• git commit -m "..."：正式存档，-m 后面引号里的是这次存档的说明，用来提醒未来的你「这一次改了啥」。

执行完，你就有了项目历史上的第一个存档点。可以敲 git log --oneline 看一眼，它会列出你的存档记录，应该能看到刚提交的那条。

3.4 一个要贯穿始终的好习惯：小步提交

这里我要特别郑重地跟你说一件事，它比任何具体命令都重要：

每完成一个小功能、每达到一个「能跑通」的状态，就提交一次。

不要憋大招。很多人喜欢等写了一整天、改了几十个文件才想起来提交一次，这是很危险的——一旦出问题，你只能退回一整天之前，中间的辛苦全白费。

正确的节奏是：做完一小步，就 git add . && git commit -m "说明" 存一次档。 比如「实现了记账功能」提交一次，「加上了统计功能」再提交一次。这样你的项目历史就像一串清晰的脚印，任何时候出问题，最多只损失一小步。

至于提交说明（-m 后面的内容）怎么写，有个简单又好用的惯例，用几个常见的前缀开头：

• feat: 表示新增了一个功能（feature）
• fix: 表示修好了一个 bug
• chore: 表示一些杂务、配置类的改动
• docs: 表示改了文档
• refactor: 表示重构（代码结构调整，但功能没变）

比如 feat: 支持按月统计消费、fix: 修复金额为负时的崩溃。这样将来回头看历史，一眼就懂每一步在干嘛。我们后面全程都会用这个习惯，你会慢慢形成肌肉记忆。

3.5 第一次和 Qoder 面对面

好了，规矩立完了，现在正式唤醒我们的 AI 搭档。

确保你还在 ledger 文件夹里，然后敲：

qoder

回车后，终端会切换成 Qoder 的对话界面。你会看到一个可以输入文字的地方，光标在那儿等你说话。

我们别客气，直接跟它打个招呼、说说我们的打算。你可以输入类似这样一段话（用你自己的话说也行，它懂人话）：

你好！我想做一个叫「记账小管家」的命令行小工具，用 Python 写。它能让我记录每一笔收入和支出，之后还能按分类、按月份统计消费。我们先从最基础的开始，你先别急着写代码，我们先聊聊这个工具大概需要哪些功能、项目结构怎么设计比较好。

发送之后，留意观察它怎么回应。一个好的 AI 工程师不会上来就闷头写代码，而是会先跟你确认需求、理清思路——Qoder 就是这样。它可能会反问你几个问题，或者给你一个初步的功能清单和结构建议。你就顺着跟它聊。

这一步我们先不动手写代码，目的只是让你熟悉「和它对话」这件事，感受它的节奏。等聊清楚了，下一章我们再让它真正开始搭项目。

3.6 先学会两个动作：/help 和「斜杠命令」

正式让 Qoder 干活之前，先教你两个会陪你走完整个教程的小动作。

第一个：随时敲 /help。 在 Qoder 的对话框里输入 /help 回车，它会列出当前可用的命令和用法。以后任何时候你「不知道能敲什么」，/help 就是你的救生圈。

第二个：认识「斜杠命令」。 你会发现，在对话框里输入一个斜杠 /，会弹出一大串可选命令。这些以 / 开头的命令，叫斜杠命令（slash commands），是 Qoder 预置的快捷操作——不用啰嗦描述，敲一个命令它就懂。它们大致分几类，你先混个眼熟，后面用到时我都会细讲：

• 会话类：/new（开新对话）、/clear（清空当前上下文）、/resume（找回以前的对话）等；
• 模式类：/plan（先规划不动手）、/tasks（任务清单）等；
• 代码类：/diff（看改动）、/review（代码审查）、/init（初始化项目约定）等；
• 工具类：/mcp、/skills、/agents、/memory、/permissions 等。

你完全不用背。记住一句话就行：想做什么，先敲个 / 看看有没有现成命令。 这比你每次都打一大段自然语言去描述要高效得多。

3.7 用 /init 给项目立一份「约定」，而不是手写

回到第 3.3 节，我带你手写了 .gitignore。那是为了让你理解它的原理。但项目里还有另一份更重要的「规矩文件」——AGENTS.md，这个我强烈建议让 Qoder 用 /init 命令自动生成，而不是手写。

AGENTS.md 是什么？它是你给 Qoder 定的项目说明书：这个项目用什么语言、遵循什么规范、有什么必须遵守的约定。Qoder 每次进入这个项目，都会先读它，然后照着做。这相当于给 AI 定了一份「入职须知」，让它每次都表现稳定，而不是每次都像新来的实习生。

怎么生成？在对话框里敲：

/init

Qoder 会自动扫描你的项目，然后生成一份 AGENTS.md，把它观察到的技术栈、目录结构、约定都写进去。生成后你打开看看、按需改改就行。对我们这个还几乎是空的项目，它可能写得比较简单，没关系——随着项目长大，你可以随时再 /init 更新，或手动补充。

这里顺便把 Qoder 的「记忆」体系给你交个底，它分两层，你现在理解个大概即可，第 6 章会展开：

• 静态记忆（你/团队写的规矩）：主要就是 AGENTS.md。它有两个层级——
  • 项目级：放在项目根目录 <项目>/AGENTS.md（只管这个项目）；
  • 用户级：放在 ~/.qoder/AGENTS.md（对你所有项目生效）。
  • 此外还能在 <项目>/.qoder/rules/ 下放更细的规则文件。
• 自动记忆（Qoder 自己记的）：它会把一些可复用的信息默默存在本地（路径大致是 ~/.qoder/projects/<项目>/memory/）。你可以用 /memory 命令查看，或者直接用大白话跟它说「记住：这个项目金额一律用整数分存储」「忘掉之前关于 XX 的记忆」。

/init 生成好 AGENTS.md 后，别忘了把它也提交进 git：

git add .
git commit -m "chore: 用 /init 生成项目约定 AGENTS.md"

3.8 认识「权限模式」：你始终是掌舵的人

工作状态与权限模式分别选择。计划状态负责先调查和出方案；权限模式决定工具授权，不能把 plan 与 default 等混成同一层级。

当前官方标准权限名包含 default、accept_edits、auto、dont_ask、bypass_permissions。教学使用默认逐项确认，写文件前查看实际授权；旧 --permission-mode plan 只是兼容入口。/permissions 管理权限规则，不把它描述成所有工作状态的切换器。

先保存 qoder --version 和 qoder --help。交互切换依当前界面的 Shift+Tab 提示，启动时用本机帮助支持的 --permission-mode 标准值；遇到界面差异按能力检查，不猜名称。

参考：Qoder 官方文档。

06 第一个可用功能

4.1 准备起点

把 ledger-starter 复制到自己的 ledger 目录，使用 Python 3.10+。macOS/Linux 运行 python3 -m venv .venv 并 source .venv/bin/activate；Windows 用 py -m venv .venv 后激活，或直接使用 .venv\Scripts\python.exe。确认 python --version 和 git --version；本课参考验收使用 unittest，无需装 pytest。

初始化 git init -b main，先看 .gitignore 排除了 data 和 reports，再提交起点。

4.2 交给 Qoder 的接口契约

先阅读 README、fixtures/september.json 和 tests/test_contract.py，只出计划。
实现根目录 ledger.py，Python 标准库，入口 python ledger.py。
全局 --data 指定 JSON 路径，默认 data/records.json。
add 必须接受 --amount（元、正数、最多两位小数）、--type（收入/支出）、--category、--date（YYYY-MM-DD）、--note。
存储数组，每条字段 id、amount_cents（整数分）、type、category、date、note；ID 递增。
数据不存在按空数组；坏 JSON 或非法字段给出明确错误并非零退出，不覆盖原文件。
本章先实现 add、list；summary/report 在后续阶段完成。
测试使用临时目录，不能读取个人账目。退出计划状态并确认权限后才修改实现。

需求不再随生成结果改变。查看计划后先实现 add/list，再核对实际 diff。卡住时可看 参考实现，但先解释差异，不能跳过验收。

4.3 固定日期，得到可手算的数据

下面在新的 data/course-september.json 中运行一次，重复运行会重复追加，已有数据时先换一个新的实验文件名：

python ledger.py --data data/course-september.json add --amount 8000 --type 收入 --category 工资 --date 2026-09-01
python ledger.py --data data/course-september.json add --amount 35 --type 支出 --category 餐饮 --date 2026-09-02
python ledger.py --data data/course-september.json add --amount 12 --type 支出 --category 交通 --date 2026-09-03
python ledger.py --data data/course-september.json list

预期恰好三条，整数分分别为 800000、3500、1200，月份均为 2026-09。使用固定日期使任何月份跟学都得到同一结果。非法金额 0.001 应报错且文件不变。

4.4 接到下一章

下一章先补 summary --month YYYY-MM，再用 starter 的 contract test 验证收入 800000、支出 4700、结余 795300。第 7 章 report 使用相同数据与口径，加 --export 写 CSV。data 文件不会进入 Git，Git 提交不能恢复被忽略的个人账目。

提交前看 git status、git diff 与 git diff --cached，只暂存 ledger.py、tests、fixture、README、.gitignore。后续通用闭环沿用这一节，不重复启动和提交的全部步骤。

07 调试测试与重构

上一章我们的「记账小管家」已经能记账了。但一个只会记、不会算的账本，价值有限——记账的意义，恰恰在于回头看清楚钱花哪儿去了。

所以这一章我们要给它加上「统计分析」的本事。但在加功能之前，我想先带你经历每个程序员都逃不掉的两件事：遇到 bug、以及用测试防住 bug。

我会故意制造一个 bug，让你看看 Qoder 是怎么像个老练的侦探一样排查问题的。学会了这个，你以后面对满屏红色报错时，就不会再手心冒汗了。

5.1 先来点刺激：制造一个 bug，看 Qoder 怎么破案

先完成 summary --month YYYY-MM，沿用第 4 章整数分字段，运行 python -m unittest discover -s tests -v。固定九月样例应收入 800000、支出 4700、结余 795300；不一致时先打印被纳入统计的三条记录。

然后在独立的 data/broken-lab.json 写入 {broken，调用 python ledger.py --data data/broken-lab.json list。这是确定的非法输入，不依赖 AI 恰好写出某种缺陷。用前后文件内容或哈希确认程序没有覆盖它。不要修改个人 records.json。

5.2 把报错交给 Qoder：正确的求助姿势

把实际命令、工作目录、退出码和 stderr 交给 Qoder，要求只分析。预期是非零退出和清楚的“数据格式错误”提示；若出现 Traceback 或覆盖原文件，先写失败回归测试再修复。若原本已友好处理，直接补回归覆盖，不把“没有 bug”当作复现失败。

坏 JSON 位于专用文件，实验结束可保留为 fixture；无需恢复或删除个人数据。进入重构前完整测试必须全绿，记录提交号作为下一章起点。

5.3 给代码上保险：让 Qoder 写测试

刚才那个 bug，是我们手动去试探才发现的。但手动试探有个大问题：你今天试了负数，明天改了代码，又得重新试一遍，谁受得了？

这就需要自动化测试——写一段专门的代码，让它自动去检查「你的程序在各种情况下表现对不对」。以后每次改动，跑一遍测试，几秒钟就知道有没有把原来好的功能改坏。这就是程序员常说的「测试是一张安全网」。

很多人不爱写测试，觉得枯燥又费时。而这恰恰是 Qoder 最能帮你省心的地方之一。跟它说：

帮我为记账工具写一些单元测试，用 Python 标准的 unittest 就行（不用装额外的东西）。重点覆盖这些情况：正常记一笔账、统计收入和支出的总额、以及金额为负数或数据异常时程序不应该崩溃。

Qoder 会创建一个测试文件（通常叫 test_ledger.py 之类），并写好一个个测试用例。写完之后，让它运行测试，或者你自己跑：

python3 -m unittest discover

如果一切正常，你会看到类似 OK 的字样，以及跑了几个测试。如果某个测试失败了，它会显示 FAILED 并告诉你是哪个——这时候又可以像 5.2 那样，把失败信息交给 Qoder 去查。

让 Qoder 自己把关：/verify。 除了手动跑测试，Qoder 内置了一个 /verify 技能，专门用来「验证改动是否真的成立」。敲 /verify，它会主动去运行相关测试、检查功能是否按预期工作，把「我以为改好了」变成「我验证过确实好了」。养成「改完就 /verify 一下」的习惯，能帮你挡掉大量「看着对、其实错」的问题。

这里我想让你建立一个观念：有了测试之后，你后面再改代码就「有底气」了。因为你随时能一键验证「我这么改，有没有把别的地方弄坏」。测试不是负担，而是让你敢于大胆修改的靠山。而 Qoder 帮你把写测试这件苦差事变得轻松，你就更没有理由偷懒了。

测试写好了，也提交一下：

git add .
git commit -m "test: 为记账和统计功能添加单元测试"

5.4 顺势重构：加一个「按分类统计」的功能

现在我们有功能、有测试、有存档，是时候做一次「优雅地长大」了。

我们来加一个更实用的功能：按分类看消费。比如「这个月餐饮花了多少、交通花了多少」。跟 Qoder 说：

现在我想加一个功能：按分类汇总支出，让我能看到每个分类各花了多少钱。请你先看看现有的代码结构，如果为了让这个新功能加得干净、不破坏原有逻辑，需要调整一下代码的组织方式，你可以顺便重构一下。改完记得跑一遍我们已有的测试，确保没把原来的功能弄坏。

这段话里藏着一个很重要的做法，我要单独点出来：「改完跑一遍已有测试」。

这就是前面写测试的回报时刻。当 Qoder 一边加新功能、一边调整（重构）老代码时，我们最怕的就是「新的加上了，老的搞坏了」。而有了测试，它每改一步都能自动验证，你也就能放心。重构（refactor）这个词你可能会觉得玄乎，其实说白了就是：在不改变功能的前提下，把代码整理得更清晰、更合理。 就像把乱糟糟的抽屉重新归置一遍，东西还是那些东西，但用起来顺手多了。

想专门给代码「瘦身」：/simplify。 如果你不是加功能，而是单纯觉得某段代码写得啰嗦、想让它更简洁干净，可以敲 /simplify。这个技能专门做「在不改变行为的前提下，把代码简化、整理」。重构完同样记得 /verify 跑一遍测试，确认功能没变。

等它做完、测试全绿（全部通过），你再亲自跑一下新功能确认效果：

python3 ledger.py summary --by-category

（命令以实际实现为准。）看着自己一点点做大的工具，是不是挺有成就感？

存档：

git add .
git commit -m "refactor: 重构数据结构并支持按分类统计"

5.5 第一道后悔药：/rewind 撤销 Qoder 的改动

在动用 git 之前，我要先教你一个更贴身、更常用的「后悔药」——/rewind。

场景是这样的：Qoder 刚帮你改了一通代码，结果越改越乱，或者你压根就不喜欢它这次的改动，想「当作它没动过」。这时候你不需要去折腾 git，直接敲：

/rewind

它会弹出一个检查点（checkpoint）列表——Qoder 在干活的过程中会自动打下一个个「快照」，记下每个节点的状态。你从列表里挑一个想回到的时间点，然后选择要恢复什么：

• 只恢复对话：把聊天上下文退回到那时候，但代码保持现状；
• 只恢复文件：把代码退回到那时候的样子，对话不动；
• 两者都恢复：对话和代码一起「穿越」回去。

对「AI 刚改坏了、我想立刻退回它动手之前」这种高频情况，/rewind 是最快、最省心的解法——它专门管 Qoder 自己造成的改动，一步到位。

那 /rewind 和 git 有什么区别？ 一句话记住：

/rewind 管的是「Qoder 这一轮改了啥」，粒度细、随手就能撤；git 管的是「整个项目的历史存档」，粒度粗、但永久可靠、还能跨设备。 两者不冲突，是两层保险。

所以实际的后悔顺序应该是：先想 /rewind（撤销刚才的 AI 改动）；如果问题更大、要退回某个更早的「正式版本」，再动用 git。

5.6 更大的回退：动用 git 存档

如果 /rewind 也救不了你——比如你想退回的是好几个功能之前、某个已经 git commit 存档过的「正式版本」——这时候 git 的存档就派上大用场了。先看看你都有哪些存档点：

git log --oneline

它会列出你的提交历史，每一行是一个存档，前面有一串字符（叫 commit 哈希，比如 a1b2c3d）。

在动手回退之前，我要特别郑重地提醒你一件事：git 的回退操作里，有一些是「会丢弃你未保存的改动」的，用错了可能把你还没提交的心血弄没。所以：

• 回退前先敲一句 git status，看看有没有「改了但还没提交」的东西。如果有，而你又不确定要不要留，可以先用 git stash 把它们临时收起来（相当于「先放进口袋，别丢」），这样最安全。
• 如果你只是想看看某个旧版本长啥样，而不想真的退回去，可以用 git checkout <哈希> 去「参观」一下，看完再 git checkout main（或你所在的分支名）回来。
• 真正要把项目彻底退回某个存档点，是个需要谨慎的操作。在你还不完全清楚后果之前，我建议你不要自己乱敲那些带有 --hard、reset 字样的命令，而是直接问 Qoder：「我想把项目安全地退回到上一个能用的版本，应该怎么做？会不会丢掉我没保存的东西？」让它结合你的具体情况给你最稳妥的命令，并在你理解每一步含义后再执行。

我把这一点讲得这么啰嗦，是因为**「删数据、回退」这类操作一旦做错，代价很高、又很难挽回。** 养成「危险操作前先问清楚、先保护好未保存的东西」的习惯，会让你在漫长的编程生涯里少掉很多头发。

好消息是：正因为我们从头就坚持小步提交，你现在其实很少需要「大回退」——最多也就是退回最近的一个存档，损失的不过是几分钟的工作量。看，好习惯又一次保护了你。

这一章信息量不小，我们经历了完整的「酸甜苦辣」：遇到 bug 用 /debug 请 Qoder 破案、用 /verify 跑测试上保险、在测试保护下用 /simplify 安全重构、还学会了先用 /rewind 撤销 AI 改动、再必要时动用 git 回退。 你还第一次真切体会到：内置的 skill（/debug /verify /simplify）就是 Qoder 替你把「专业流程」打包好了，敲一个命令就能用上。

到这里，你的「记账小管家」已经有了记账、汇总、按分类统计的能力，而且代码有测试兜底、历史有 git 记录。它已经像模像样了。

下一章，我们跳出这个小程序，去见识 Qoder 更广阔的天地：怎么让它帮你在陌生代码库里探路、怎么用 skills 和 MCP 把它连接到外部世界、怎么让它记住你的偏好越用越懂你。

翻到第 6 章，我们打开格局。

08 进阶工作流

前面五章，我们围绕「记账小管家」把 Qoder 的基本功练扎实了：对话、写功能、调试、测试、重构、git 存档。你现在已经能独立完成一个小项目了。

这一章，我想带你把视野打开一点，去认识 Qoder 身上几个更「高级」但也更迷人的能力。它们不一定每个都马上用得到，但知道它们存在、大概什么时候用，会让你在遇到对应场景时，心里「咯噔」一下想起来：哦，这个可以用 Qoder 的那招。

我们还是尽量结合「记账小管家」来讲，让抽象的能力有具体的落脚点。

6.1 让 Qoder 当你的「代码库向导」

我们的记账项目现在文件不多，你闭着眼都知道东西在哪。但想象一下：哪天你接手了一个别人写的、有几百个文件的大项目，光文件树就滚好几屏，完全无从下手。这是职场里太常见的场景了。

Qoder 特别擅长这个——它能替你「翻遍」整个代码库，然后用一句话回答你的问题。 你不用自己去一个个文件点开找。

比如你可以直接问它：

• 「这个项目的入口在哪？程序是从哪个文件开始跑起来的？」
• 「记录账目的数据，是在哪个函数里被写进文件的？」
• 「有没有哪个地方处理了『金额为负』的情况？都怎么处理的？」

它会去搜索、去阅读相关文件，然后把答案连同「在哪一行」一起告诉你。你甚至能顺着它给的线索，直接跳到那段代码去看。

这背后其实是一种叫「探索式搜索」的能力——它不是死板地匹配关键词，而是理解你的意图，哪怕你用的词和代码里的不完全一样，它也能找对地方。所以当你面对一个陌生项目、心里发怵的时候，记住：别自己硬啃，先让 Qoder 给你当向导。

6.2 Skills：把「专业流程」打包成一个命令

先用 /skills 查看可发现的技能；本节只做一个自定义检查闭环，其余命令查附录。

在用户技能目录 ~/.qoder/skills/ledger-check/SKILL.md 创建：

---
name: ledger-check
description: 检查记账课程的接口和固定九月样例
---
读取项目 README 与 tests/test_contract.py。
只运行 python -m unittest discover -s tests -v，不修改实现、测试或数据。
报告命令、退出码、失败测试名；未运行时明确写未运行。

重开会话后在 /skills 中确认 ledger-check 被发现，再显式要求使用它。自己在另一个终端运行同一测试并核对报告；若未发现，先检查目录和 frontmatter，不继续叠加插件。

6.3 MCP：给 Qoder 接上「外部世界」

如果说 skill 是 Qoder 的「内功」，那 MCP 就是它伸向外部世界的「手」。

MCP（全称 Model Context Protocol，模型上下文协议）这个词听着唬人，其实概念很好懂：它是一套标准，让 Qoder 能够连接和操作外部的工具与数据源。 默认情况下 Qoder 主要在你的本地文件里活动；接上 MCP 之后，它就能操作真实浏览器、连数据库、调外部接口等等。这些能力由一个个「MCP 服务器」提供——你可以把它想象成给 Qoder 插不同的「外接设备」。

怎么装一个 MCP 服务器？ 最省事的方式是用命令添加。语法是：

以下为参数模板，执行前先将尖括号占位符替换为实际值：

qoder mcp add <名字> -- <启动这个服务的命令>

举个真实的例子，给 Qoder 装上一个「操作浏览器」的能力（Playwright MCP）：

先在终端检查 node --version、npm --version、npx --version；CLI 安装不要求 Node，不代表这个 MCP 也无需 Node。按 Node.js 官方安装说明补齐后，保存使用的 Node 和 MCP 包版本。第一次连接若提示缺浏览器，按 Playwright MCP 的安装提示完成浏览器准备，再验证页面实际打开。

qoder mcp add playwright -- npx -y @playwright/mcp@latest

这条命令的意思是：添加一个叫 playwright 的 MCP 服务，启动方式是 npx -y @playwright/mcp@latest（-- 后面就是「怎么把它跑起来」的命令）。装好后配套的几个管理命令：

• qoder mcp list：看看现在装了哪些 MCP 服务；
• qoder mcp remove <名字>：删掉某个；
• 如果 Qoder 正开着，敲 /mcp reload 让它重新加载；用 /mcp 可以查看 MCP 的状态。

它把配置写在哪？ qoder mcp add 会自动帮你写进配置文件，你一般不用手动改。但知道位置有好处，配置文件按作用范围分三处：

• 用户级（对你所有项目生效）：~/.qoder/settings.json
• 本地级（只对当前项目、且不提交给团队）：<项目>/.qoder/settings.local.json
• 项目级（可提交、团队共享）：<项目>/.mcp.json

添加时可以用 -s 指定写到哪个范围（user / local / project），用 -t 指定服务类型（stdio / sse / http / ws，默认 stdio 就行）。

如果你想手动写配置，格式长这样（以项目级 .mcp.json 为例）：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    }
  }
}

回到我们的记账项目，一个生活化的用法：假设你想让「记账小管家」能自动去网上拉汇率。装上一个浏览器类 MCP（比如上面的 playwright）后，你就可以对 Qoder 说：「帮我打开这个网页，把今天的美元兑人民币汇率读出来。」这只表示开发 Agent 能读取网页，不代表最终记账程序已经能联网取汇率。应用自动取数还需实现 HTTP 客户端、数据源、单位、时间戳、超时与离线策略。本课仅验收 Agent 打开指定页面并返回标题，不把它当作账本运行时能力。

如果你觉得手写配置麻烦，还可以用 /mcp-config 这个 skill，让 Qoder 引导式地帮你把 MCP 配好。

MCP 属于「进阶中的进阶」，你现在只要知道有这么回事、知道用 qoder mcp add 就能装就够了。等真遇到「想让 Qoder 连某个外部工具」的需求，再回来照这一节操作，很有针对性。

6.4 子代理：让 Qoder 学会「分身术」

有些任务又大又杂，比如「把整个项目里所有中文注释翻译成英文」，或者「在一个几百个文件的陌生代码库里找出所有和支付相关的逻辑」。让 Qoder 一个人从头干到尾，会很慢，而且中间产生的海量信息会把它的「注意力」（上下文）占满。

这时候可以用子代理（subagents）——Qoder「派出分身」去处理相对独立的子任务，分身干完把干净的结论汇报给「本体」，本体再汇总。好处有两个：能并行（几件互不干扰的事同时做，快）、保护主线（脏活累活丢给分身，本体思路不被淹没）。

Qoder 内置了哪几种子代理？ 你会经常遇到这三个：

• Explore（探索）：只读的「代码库侦察兵」。按关键词、文件模式、或「某功能在哪实现」去快速定位代码。6.1 节说的「代码库向导」，主力就是它。
• Plan（规划）：只读的「架构参谋」。帮你设计实现方案、理清要动哪些文件、有哪些依赖和取舍，但不动手改代码。
• general-purpose（通用）：全能型分身，适合复杂搜索、跨多文件分析、调用链追踪这类需要多步骤的活。

怎么用？ 大多数时候你不用手动指派，Qoder 会自己判断该不该派分身、派哪个。但你也可以主动点名，比如：

用 Explore 子代理帮我找出项目里所有读写 records.json 的地方。

或者在提需求时给个提示：「这个任务比较大，你可以拆成几块并行处理。」

还能自定义子代理。 如果你有一类反复出现的专门任务（比如「按我们团队规范审查 API 设计」），可以造一个专属子代理：在项目的 .qoder/agents/ 目录（或用户级的 ~/.qoder/agents/）下放一个 .md 文件，描述这个代理的职责和规则即可。造好之后用 /agents 可以查看和管理。

对新手，你平时不用操心子代理——知道「遇到大任务它有分身术、并且有 Explore / Plan / general-purpose 这几员大将」就够了。

6.5 记忆与项目约定：让 Qoder 越用越懂你

最后一个能力，我个人觉得特别有意思——它让你和 Qoder 的合作「有默契」，不用每次从头交代。第 3 章我们已经用 /init 生成过 AGENTS.md，这里把整套「记忆」体系讲完整。

Qoder 的记忆分两大类：

① 静态记忆（你或团队亲手写的规矩）——核心是 AGENTS.md。

它就是你给 Qoder 定的「项目说明书」，Qoder 每次进项目都会先读它。关键是它分层级，你可以按需要放的位置：

• 用户级：~/.qoder/AGENTS.md —— 对你所有项目生效。适合放你个人的通用偏好，比如「回复尽量简洁」「解释概念时多打比方」。
• 项目级：<项目>/AGENTS.md —— 只对当前项目生效，可以提交给团队共享。适合放项目专属规范，比如我们记账项目的：

  • 本项目用 Python 3，代码风格遵循 PEP 8；
  • 所有金额以「分」为单位用整数存储，避免小数误差；
  • 每完成一个功能都要补对应的单元测试；
  • 提交信息用中文，遵循 feat/fix/docs/test/refactor 前缀规范。

• 更细的规则文件：<项目>/.qoder/rules/ 目录下可以放多个 .md 规则文件，还能给规则设「触发方式」——比如始终生效、手动触发、由模型自行判断是否相关、或只在匹配某类文件时生效（glob）。需要精细化管理时用得上。规则文件里还能用 @路径/文件名 的写法引入别的文件内容。

AGENTS.md 一般用 /init 自动生成后再手动补充，不用从零手写。

② 自动记忆（Qoder 自己记的）。

除了你手写的规矩，Qoder 还会把一些「值得复用」的信息自动记在本地（路径大致是 ~/.qoder/projects/<项目>/memory/），下次对话自动用上。你可以主动管理它：

• 让它记：直接说大白话「记一下，这个项目的金额一律用整数分存储」，或者用专门的 /remember 命令把某条信息存进记忆。
• 查看/管理：敲 /memory 查看当前所有记忆文件、打开自动记忆的目录；敲 /memory manage 编辑或删除某条记忆。
• 让它忘：直接说「忘掉之前关于 XX 的记忆」。

为什么这件事值得你认真对待？ 因为它把我们前面辛辛苦苦养成的好习惯「自动化」了。你把「git 小步提交、提交信息规范、改完必跑测试、金额用整数分」这些都写进项目的 AGENTS.md，会作为模型的行为约定加载，但不保证每次执行。强制检查应由测试脚本、Git hook 或 CI 实现，并检查实际退出码，不再依赖你每回都记得去叮嘱。Qoder 一进项目就照着办，表现得稳定又可靠，而不是每次都像新来的实习生。

给你留个小作业：现在就用 /init 生成（或打开已有的）AGENTS.md，把我们这一路强调的几条规矩写进去，然后开个 /new 新对话，让它做点小事，观察它是不是自动就遵守了这些约定。那种「它记住了并照做」的默契感，你会印象很深。

这一章我们见识了 Qoder 更辽阔的一面，而且都落到了真实命令上：用 Explore 子代理当代码库向导、用 /skills 里的现成技能（/debug /verify /security-scan 等）提效、用 qoder mcp add 通过 MCP 连接外部世界、用 Explore / Plan / general-purpose 三员大将并行作战、靠 /init 生成的 AGENTS.md 加 /remember、/memory 让它越用越懂你。

它们看起来五花八门，但内核其实是一致的：Qoder 想成为你越来越称手的伙伴，而不只是一个问答工具。

下一章，我们要把「记账小管家」收尾成一个真正「拿得出手、能交付」的作品——加上导出报告这样的实用功能、生成一份像样的文档、整理出一份漂亮清晰的提交历史。

翻到第 7 章，我们把这个作品打磨完整。

09 综合实战与交付

走到这里，你的「记账小管家」已经能记账、能汇总、能按分类统计，还有测试兜底、有 git 记录。它从一个空文件夹，长成了一个像样的小工具。

但一个「自己能跑」的工具，和一个「拿得出手、能交给别人用」的作品，中间还差最后一段路。这一章，我们就来走完它：加一个真正实用的功能、写一份让别人一看就懂的文档、再把整个项目的收尾工作做得漂漂亮亮。

做完这一章，你收获的不仅是一个完整的记账工具，更是一套「如何有始有终地做完一个项目」的完整经验。

7.1 加一个「拿得出手」的功能：导出月度报告

记账的最终价值，是能回头看清「这个月我的钱都花哪儿了」。所以我们的收官功能，就做一个导出月度消费报告——把某个月的收支，整理成一份清清楚楚的报告，还能导出成文件保存下来。

唤醒 Qoder，把需求讲清楚（记得我们的老规矩：让它先说思路，你同意了再动手）：

我想加最后一个功能：生成月度报告。

• 我可以指定某个月（比如 2026-09），它就把那个月的账目汇总出来：总收入、总支出、结余，以及按分类的消费明细；
• 报告先在命令行里好看地打印出来；
• 再支持导出成一个 CSV 文件，方便我用 Excel 打开或者存档。 你先讲讲打算怎么实现，尤其是 CSV 导出这块，我同意了再写。写完之后，别忘了给这个新功能补上单元测试，并跑一遍全部测试确保没弄坏老功能。

你看，这段话里我们把前几章养成的习惯全都自然地带上了：先方案后动手、写完补测试、跑全量测试保平安。这些已经不再是我提醒你才做的事，而是变成了你提需求时的「标准动作」——这就是成长。

等 Qoder 实现完，你亲自验证一下：

python ledger.py --data data/course-september.json report --month 2026-09
python ledger.py --data data/course-september.json report --month 2026-09 --export report.csv

（命令名、字段与单位沿用第 4 章固定契约。）第一条在终端里打印报告，第二条会额外生成一个 report.csv 文件。你可以用 Excel 或任意表格软件打开那个 CSV 看看，数据是不是一目了然。

验证通过后，存档：

提交前先在 .gitignore 加入 report.csv、reports/、data/；保留课程 fixtures，不要用宽泛规则误忽略样例。检查 git diff --cached，已暂存的报告用 git restore --staged -- report.csv 取消暂存；已经提交的报告需另作移除提交，添加忽略规则不会清除历史。

git add ledger.py tests README.md .gitignore
git commit -m "feat: 支持生成并导出月度消费报告"

小提醒：导出的 report.csv 是你的个人数据产物，和之前的 data/ 目录一样，通常不该提交到 git。如果发现 git status 里冒出了 .csv 文件，可以在 .gitignore 里加一行 *.csv 把它们排除掉，再提交。

7.2 让 Qoder 帮你写文档

一个好项目，得有一份「说明书」，让别人（也包括三个月后已经忘了细节的你）打开就知道这是啥、怎么用。这份说明通常写在一个叫 README.md 的文件里。

写文档是件枯燥的事，而这正是 Qoder 的强项。跟它说：

帮我给这个项目写一份 README.md。要包含：这个项目是干什么的、需要怎么安装和运行、每个命令怎么用（记账、汇总、按分类统计、月度报告都写上，最好各给一个例子）、以及数据是怎么存的。语气友好一点，让没用过的人一看就会上手。

Qoder 会通读你的代码，然后写出一份结构清晰的 README。你读一遍，看看有没有和实际不符的地方——它偶尔会「想当然」地写上一个其实并不存在的用法，所以审核这一步不能省。有不对的地方，直接告诉它改。

写好了，提交：

git add ledger.py tests README.md .gitignore
git commit -m "docs: 添加项目 README 使用说明"

到这里，你的项目就有了代码、有测试、有文档——三件套齐活，这是一个「正经项目」该有的样子。

7.3 交付前把把关：/review、/security-scan、/export

代码写完、文档也有了，别急着收工。一个负责任的项目，在「交付」前还应该过两道检查。这正是把前面学的 skill 用起来的好时机。

第一道：代码审查 /review。 在对话框敲 /review，让 Qoder 以「审查者」的身份把你这一版代码通读一遍，挑出潜在问题：有没有边界情况没处理、有没有写得别扭的地方、有没有更清晰的写法。它给出的意见你不必全盘接受，但值得逐条看一眼——这就像交卷前自己再检查一遍，常常能捞出一些藏得比较深的小毛病。

第二道：安全扫描 /security-scan。 敲 /security-scan，让它检查代码里有没有安全隐患（比如把敏感信息硬编码、对用户输入缺乏校验等）。对我们这个小工具来说也许问题不多，但养成「交付前扫一遍安全」的意识非常重要——将来你写的是真实上线、别人会用的程序时，这一步能帮你避开大麻烦。

两道检查过完、该修的修好、该提交的提交，你就可以把这个版本「封存」了。这时可以用 /export 把你和 Qoder 这一路的对话导出保存成一个文件——它相当于你这个项目的「开发过程记录」，将来回顾「当初这个功能是怎么一步步做出来的」，会非常有价值。

7.4 收尾：整理出一份漂亮的提交历史

现在我们来欣赏一下自己的劳动成果。敲：

git log --oneline

你应该能看到一串清晰的提交记录，从上到下大概是这样一条成长轨迹（具体文字以你的为准）：

docs: 添加项目 README 使用说明
feat: 支持生成并导出月度消费报告
refactor: 重构数据结构并支持按分类统计
test: 为记账和统计功能添加单元测试
feat: 增加收支汇总统计
feat: 实现记一笔账功能
chore: 初始化项目

停下来，认真看一眼这个列表。 它就像一部浓缩的开发史，每一步做了什么、按什么顺序做的，一目了然。这就是我们从第一章就坚持「小步提交 + 规范前缀」的回报——现在，任何人（包括未来的你）看一眼这段历史，就能明白这个项目是怎么一步步长起来的。

如果你想给这个「第一个完整版本」做个特别的标记，可以打一个 tag（标签），相当于在历史上插一面纪念旗帜：

git tag v1.0

以后敲 git tag 就能看到它。这个 v1.0 就代表着「记账小管家的第一个正式版本」。

7.5 进阶一步（可选）：把项目备份到远程仓库

先在自己的 GitHub 账号创建目标仓库，复制其 URL；本节只备份已确认不含个人账目和凭证的提交。

git remote -v
git branch --show-current

没有 origin 时运行 git remote add origin <你创建的仓库URL>（替换占位符）；已有 origin 则先确认目标，不能覆盖指向。随后 git push -u origin main，按 Git 的认证提示完成操作，并在仓库页面核对提交号。

/setup-github 是 GitHub Actions 集成入口，不是首次 remote/push 的替代命令；当前官方说明 CN 版本不可用，作为独立选修看待。

7.6 回顾：这一路，你到底学会了什么

在合上这个项目之前，我们花点时间回头看一眼。你从第 1 章那个「Qoder 是什么都还不太清楚」的状态，到现在，其实已经悄悄掌握了一整套东西：

关于 Qoder 的核心能力，你亲手用过：

• 和它对话、把需求讲清楚；
• 用 /plan 让它先规划、再动手，并通过 /diff /review 审核它的每一步改动；
• 遇到 bug 时用 /debug 找根因、做修复；
• 让它写测试、用 /verify 把关，给自己建一张安全网；
• 在测试保护下用 /simplify 放心重构、加功能；
• 用 Explore / Plan / general-purpose 子代理探索代码库，用 skills、MCP、记忆等进阶能力；
• 改坏了用 /rewind 一键撤销，用会话命令保持上下文干净；
• 让它写文档，用 /review /security-scan 做交付前把关，用 /export 存档开发过程，用 Git remote/push 推送到远程。

关于开发习惯，你已经内化了：

• 小步提交：做完一小步就存档，从不憋大招；
• 规范提交信息：用 feat / fix / docs / test / refactor 前缀，让历史可读；
• 先方案后动手：让 AI 先讲思路，确认了再写，少返工；
• 每次改动都审核：方向盘始终在自己手里；
• 改完跑测试：确保没弄坏老功能；
• 危险操作先问清楚：回退、推送这类高风险动作，不盲干。

说实话，这套习惯，比这个记账工具本身值钱得多。 工具是你练手的载体，而这些习惯会跟着你走进未来每一个项目。

到这里，我们的实战部分就圆满收官了。你已经用 Qoder 从零做出了一个完整、可用、有文档、有版本管理的小项目。

最后一章，我们回到第 1 章埋下的那个伏笔——去看看 Qoder 的图形化形态 Desktop / IDE 长什么样、怎么用，以及它和我们用了一路的 CLI 到底该怎么选。

翻到第 8 章，我们给整本教程画个圆满的句号。

10 Qoder桌面版简介

本章选定 Qoder IDE，不把独立 Qoder 产品与 IDE 合称 Desktop / IDE。请从官方产品矩阵进入 Qoder IDE 下载页，选择明确支持当前系统的安装包，并记录版本。

打开第 7 章已提交的 ledger 副本，先核对项目路径、分支、Python 解释器，再让 IDE 只读说明测试入口。在集成终端运行 python -m unittest discover -s tests -v，然后做一项 README 修改并查看 diff。

同一账号不保证 CLI 与 IDE 的本地配置、会话、模型和权限自动同步。分别确认这四项；没有被官方承诺或实际验证的同步行为，不作为课程前提。项目文件通过相同目录或 Git 共享，不依赖会话同步。

参考：Qoder 官方产品与文档。

11 附录-命令速查

这张表把本教程涉及的、以及日常最常用的命令汇总到一起，方便你日后随手翻查。不用背——忘了就回来查，或者在 Qoder 里敲 /help 和 /（看弹出的命令列表），效果一样。

在终端里启动 / 恢复 Qoder

这些是你在系统终端（不是对话框里）敲的命令：

在对话框里敲的斜杠命令

进入 Qoder 后，在对话输入框里敲下面这些 / 命令。

会话管理

模式与任务

模型与思考强度

代码

工具与扩展

常用内置 Skills（技能）

账号与设置

权限模式速记

关键文件位置速记

设置优先级（从高到低）：本地 > 项目 > 用户 > 内置默认。

说明：命令与路径以官方文档为准，新版本可能有增减。拿不准时，敲 /help 或查阅 https://docs.qoder.com 最靠谱。

12 进阶学习

这套 Qoder 教程的主线很具体。

先安装和登录，再给项目建立 Git 存档，用小步提交保留每一次可回退的状态。接着通过 /init 生成项目约定，认识权限模式，然后按照固定接口契约做第一个功能。

教程甚至特意固定日期，准备可以手算的数据。

这个细节看起来很小，却很能说明它的态度。功能不是页面跑起来就算完成，而是结果要能被人独立核对。

第 5 章继续制造 Bug，让 Qoder 根据报错排查，再补测试、重构，并分别用 /rewind 和 Git 处理不同范围的回退。第 6 章把能力扩到代码库向导、Skills、MCP、子代理、记忆和项目约定。第 7 章完成月度报告导出，再补文档、Review、安全扫描和提交历史，直到项目能交付。

所以读完整套知识库，最值得留下来的是四个真正值得复用的动作。

有存档，有契约，有验证，有交付。

有存档，AI 改错时可以回退。小步提交不是为了让 Git 历史好看，而是把风险切小。

有契约，Qoder 才知道接口、输入、输出与边界。需求模糊时，生成越快，返工也越快。

有验证，结果不靠感觉。固定日期和可手算数据，就是最朴素的验收证据。测试、Review 和安全扫描，则把证据扩到功能、质量与风险。

有交付，代码、文档、提交历史和最终检查要放在一起。一个只能在当前会话里运行的结果，还不是完整项目。

这套方法在个人练习里很有效。进入企业项目以后，它会遇到更大的尺度。

接口契约会变成跨模块、跨服务的规格。Git 小步提交会扩展到 Worktree 和并行分支。单个子代理会变成调研、开发、测试、安全和 Review 的角色协作。项目约定不只是格式规范，还要包含架构决策、 启动环境、依赖边界、权限与上线要求。

Skills 和 MCP 也会从能不能接上，变成接上以后是否安全、稳定、可审计。

一个 MCP 工具可以让 Qoder访问外部系统，但谁能调用，参数怎样校验，失败是否重试，调用是否留痕，都要由工程系统负责。一个 Skill 能打包专业流程，但流程本身也需要版本、测试与清晰输出。

还有一个更难的问题，怎样把业务需求变成 Agent 真正能执行的工作单元。

教程里的固定契约已经给了起点。再往前，需要把模糊目标整理成 spec、plan 和 tasks，明确非目标、风险与验收。新项目可以先建立完整规格，老项目则要控制增量修改范围，避免 AI 为了实现一个

功能顺手重写半个系统。

「企业级 AI 编程实战营」承接的正是这种规模升级。

课程围绕 SDD 与 Harness Engineering，把规格定义、项目规则、权限、Hooks、测试、 Subagents、Worktrees、Skills 和 Slash Commands 组合成可控工作流。重点不是多学一个编程助手，而是让同一套方法能够进入复杂项目。

AI 智能体操作系统项目训练从零设计 Agent Runtime、多模型路由、MCP 和工作空间隔离。分布式延时投递服务训练复杂系统、高可用、故障切换与消息可靠性。Dify 二次开发训练大型陌生代码库的理解、增量规格与回归边界。mq9 开源协作则把交付放进真实维护者 review，最终是否合并以实际 review 为准。

扫码添加学习顾问，领取完整大纲和试听资料