Kimi Code

01 学习交流群

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

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

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

02 初识-Kimi_Code

在正式敲下第一行命令之前，我们先花一章的篇幅，把几个最基础的问题聊清楚：Kimi Code 到底是什么？它能帮你做什么？它有哪几种形态，你该选哪一个？

这一章不需要你动手操作，安心读完就好。但这些认知很重要——很多人对 AI 编程工具的误解，都是从"没搞清楚它是什么"开始的。

1.1 Kimi Code 是什么

一句话概括：Kimi Code 是一个 AI 编程 Agent——你用自然语言交代任务，它自己动手读代码、改文件、跑命令，把开发任务从头到尾做完。

如果你用过网页版的 AI 聊天助手，可能会想：不就是让 AI 写代码吗？我把需求发给它，它生成一段代码，我复制粘贴过来，不就行了？

不太一样。聊天式的 AI 更像一位"电话顾问"：你描述问题，它口头给你建议，但动手的永远是你自己——它说"你应该在 src/utils.ts 里加一个函数"，然后你得自己打开文件、敲代码、跑测试，出了问题再回去问它。

Kimi Code 则是一位"坐在你旁边的同事"。你跟它说"帮我修一下这个 bug"，它会自己去翻项目里的文件，找到问题所在，动手修改，然后运行测试验证，最后告诉你它做了什么、结果如何。如果中途发现情况不对，它还会自己调整方案，或者停下来问你的意见。

这种"能自己动手"的能力，行话叫 Agent（智能体）。具体来说，Kimi Code 可以：

• 读：浏览项目文件、搜索代码、抓取网页资料；
• 写：新建、修改、删除文件；
• 跑：在终端里执行命令，比如安装依赖、运行测试、启动服务；
• 想：根据每一步的结果，自主规划下一步该做什么。

所以，与其说它是一个"代码生成器"，不如说它是一个"能干活的搭档"。你要学会的不是"怎么向它要代码"，而是"怎么跟它分工合作"——这也是本教程要教你的核心。

1.2 它能帮你做什么

知道了原理，再来看看实际场景。下面这些事情，Kimi Code 都能胜任：

写新功能。 描述清楚你想要什么，它就规划步骤、动手实现。比如："给这个应用加一个深色模式切换按钮，点击后整个页面换肤，刷新后设置不丢。"

修 bug。 把症状、复现步骤、期望行为一次性告诉它，它会定位问题、修复、跑测试确认。比如："偶现登录成功后刷新页面又跳回登录页，第二次刷新就正常了，帮我查查原因。"

读懂陌生项目。 刚接手一个不熟悉的代码仓库，可以让它先带你逛一圈："给我讲讲这个项目的架构，入口在哪，各个模块是怎么依赖的。"比自己闷头翻半天文件快得多。

重构和补测试。 "把这几个文件里重复的逻辑提取成公共函数，改完跑一遍测试，确保行为没变。"——这类边界清晰的任务，它做得又快又稳。

自动化琐事。 批量重命名文件、分析最近七天的访问日志并生成报表、把某种格式的数据全部转换成另一种……这些你不想亲手干的活儿，一句话就能派给它。

写文档。 生成 README、给没有注释的函数补文档、根据代码变更更新 CHANGELOG，都不在话下。

定时任务。 你还可以让它"每天早上九点提醒我记录体重"或者"每小时检查一次服务是否正常"，它会设置好定时任务，到点自动执行。

值得一提的是，虽然 Kimi Code 是为编程而生，但"编程"不等于"只有职业程序员才用得上"。本教程的实战项目就是一个很生活化的例子——我们会从零做一个体重管理小助手，能记录每天吃了什么、运动了多少、体重怎么变。你不需要有开发经验，跟着做就能完成；而如果你本身就是开发者，这个过程学到的方法可以直接搬回你的日常工作中。

1.3 四种产品形态，各适合谁

Kimi Code 不是一个单一的软件，而是一组产品。同一个账号、同一份会员权益，可以在不同形态里使用。我们先建立一个全局印象，后面章节再逐一深入：

为什么本教程以 CLI 为主？ 三个原因：

1. CLI 是 Kimi Code 能力最完整的形态，新功能往往也最先在 CLI 上线；
2. CLI 在各个操作系统上的体验高度一致，学会一次，到哪台机器上都能用；
3. 其他形态本质上都是 CLI 能力的延伸——VS Code 扩展和 IDE 集成的背后，跑的就是 CLI 这个核心。把 CLI 学透了，再用其他形态基本不用重新学。

Desktop 客户端我们会在最后一章单独介绍；VS Code 扩展和 API Key 的用法在第 11 章讲解。

1.4 会员、额度与模型

开始安装之前，还有几件"行政事务"需要心里有数。

需要 Kimi 会员。 Kimi Code 是会员权益的一部分，使用前先确认你的 Kimi 账号已开通相应会员。不同等级的会员，可用的模型和上下文长度不同。

额度是按周期刷新的。 使用过程中，随时可以输入 /usage 命令查看当前额度和会员状态。如果额度用完了，可以等下一个周期刷新，或者在会员页面升级。

模型可以自由切换。 登录后，在 CLI 里输入 /model 就能切换当前使用的模型。目前主要有两类可选：

• 标准模型（如 K3 旗舰模型、K2.8 Preview）：能力强，适合复杂任务，旗舰型号最高支持约 100 万 token 的超长上下文——足够一次性装进一个大型项目的全部代码；
• 高速模型（K2.7 Code HighSpeed）：输出速度可达约 260 tokens/s，适合追求响应快的日常小任务。

刚开始不用纠结选哪个，用默认的就好。等你在实战中体会到差别（比如第 6 章开发功能、第 9 章讲配置时），再根据自己的习惯调整。

注意：别把两个平台搞混了。

Kimi Code 的会员权益（订阅制，含额度）和 Kimi 开放平台的 API（按量计费）是两套体系，Base URL 和 API Key 互不通用。本教程全程使用 Kimi Code 会员权益，登录时用 /login 选择 "Kimi Code (OAuth)" 即可，不需要自己去开放平台申请 Key。

本章小结

这一章我们认识了 Kimi Code：

• 它是一个能干活的 AI 搭档（Agent），会读、会写、会跑命令、会自己规划，而不只是一个"代码生成器"；
• 它能做写功能、修 bug、读项目、重构、自动化、写文档、定时任务这些事；
• 它有 CLI、VS Code 扩展、Desktop 客户端、API Key 四种形态，本教程以 CLI 为主线；
• 使用前需要 Kimi 会员，额度用 /usage 查看，模型用 /model 切换。

下一章我们就要动手了：在你自己的电脑上安装 Kimi Code CLI。macOS、Linux、Windows（WSL2 和 PowerShell 两条路线）的安装方式略有不同，我会把每条路线的每一步都写清楚，你照着做就行。

03 安装与首次启动

上一章我们认识了 Kimi Code，这一章就动手把它装到你的电脑上，完成登录，并和它进行第一次对话。

本章的路线是：先做一点准备（2.1 节），然后根据你的操作系统跳到对应的小节安装（2.2～2.5 节，你只需要读其中一节），最后验证安装、登录、开始对话（2.6～2.8 节）。全程大约 15～30 分钟，主要取决于网速。

2.1 安装前的准备

第一件事：找到你的终端。 Kimi Code CLI 是一个运行在终端里的程序，后面的所有操作都在终端中完成。打开终端的方法：

• macOS：按 Cmd + 空格 打开聚焦搜索，输入"终端"（或 Terminal），回车。
• Linux：大多数发行版可以按 Ctrl + Alt + T，或者在应用菜单里搜索"终端"。
• Windows：点击开始菜单，搜索 "PowerShell"，回车打开。

系统自带的终端就够用。多说一句：官方建议在对真彩色和连字支持更好的终端（比如 Kitty、Ghostty）里使用，视觉效果最佳——Windows 用户用免费的 Windows Terminal 体验也不错。但这只影响好不好看，不影响功能，不必为此折腾。

第二件事：确认 Git 已安装。 在终端里输入下面这行命令，回车：

git --version

如果显示类似 git version 2.39.0 的版本号，说明已安装。如果提示"找不到命令"：

• Windows：必须安装 Git for Windows——Kimi Code CLI 需要它自带的 Git Bash 作为 shell 环境，这是硬性要求。打开浏览器访问 https://git-scm.com/download/win，下载安装包，安装向导一路保持默认选项点"Next"即可。装完后关掉终端窗口重新打开，再运行一次 git --version 验证。
• macOS：第一次运行 git 时，系统可能弹出窗口提示"需要安装 Xcode 命令行工具"，点"安装"等它装完即可。
• Linux：Debian / Ubuntu 用 sudo apt install git，Fedora / RHEL 用 sudo dnf install git。

就算你的操作系统不强制要求 Git，从下一章开始我们也会用它管理项目代码，所以这一步迟早要做。

2.2 macOS 安装

在终端里粘贴下面这行命令，回车：

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

这是官方安装脚本，它会自动完成三件事：下载最新版本的 Kimi Code、校验文件完整性、把 kimi 命令放到系统 PATH 里（这样你在任何目录都能直接运行它）。等待几秒到几十秒，看到输出结束、没有出现红色报错，就装好了。

首次启动会慢一点，属正常现象。 macOS 的 Gatekeeper 安全机制会对新下载的程序做一次检查，导致第一次运行 kimi 时启动较慢，耐心等待即可，之后就恢复正常了。如果你嫌每次检查麻烦，可以在"系统设置 → 隐私与安全性 → 开发者工具"里把你的终端应用加进去。

备选方案（npm 安装）：如果你本来就有 Node.js 环境，也可以走 npm 路线。先运行 node --version 确认版本不低于 22.19.0，然后执行：

npm install -g @moonshot-ai/kimi-code

两种方式装出来的东西一样，任选其一。没有 Node.js 环境的话，用上面的官方脚本最省事，不需要先装任何依赖。

2.3 Linux 安装

Linux 的安装命令和 macOS 完全相同：

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

如果提示 curl: command not found，先用包管理器装上 curl 再重试——Debian / Ubuntu 执行 sudo apt install curl，Fedora / RHEL 执行 sudo dnf install curl。

备选方案同样是 npm（要求 Node.js ≥ 22.19.0）：npm install -g @moonshot-ai/kimi-code。

2.4 Windows：用 WSL2 安装

Windows 有两条路线，先想清楚选哪条：

• WSL2 路线（本节）：在 Windows 里跑一个完整的 Linux 环境，然后在 Linux 环境里装 Kimi Code。适合打算认真做开发、或者目标环境是 Linux 服务器的用户——教程里的大部分命令你都可以原样照抄 macOS/Linux 的部分。
• PowerShell 原生路线（2.5 节）：直接装在 Windows 上。适合只想快速试试、不打算折腾 Linux 环境的用户。

选 WSL2 的话，按下面的步骤来：

第 1 步：用管理员身份打开 PowerShell。 右键点击开始菜单按钮，在弹出的菜单里选择"终端管理员"（或"Windows PowerShell (管理员)"）。注意一定要选带"管理员"字样的，普通权限装不了 WSL。

第 2 步：安装 WSL2。 在打开的蓝色（或黑色）窗口里输入：

wsl --install

回车后它会自动下载并安装 WSL2 和默认的 Ubuntu 系统，耐心等进度走完。（这条命令需要 Windows 10 2004 版以上或 Windows 11；如果报错，先检查系统更新，或试试 wsl --install -d Ubuntu。）

第 3 步：重启电脑。 安装完成后按提示重启。

第 4 步：创建 Linux 用户。 重启后，一个 Ubuntu 窗口通常会自动打开（没有的话，去开始菜单搜索 "Ubuntu" 打开它）。第一次启动要花一两分钟初始化，然后窗口里会提示你创建用户：

• 先让你输入用户名：用小写字母或数字，输入后回车；
• 然后让你设置密码。**这里有个大坑要提前告诉你：输入密码时屏幕上什么都不显示，没有星号、没有圆点，光标也不动——这不是卡死了，是 Linux 的传统设计，你正常输入然后回车就行。**接着它会要求再输一遍确认。

当看到类似 你的用户名@电脑名:~$ 的提示符时，说明你已经进入 Linux 世界了。

第 5 步：在 Ubuntu 里安装 Kimi Code。 回到 2.3 节，照做即可——就是那条 curl 命令。

以后怎么用： 每次想用 Kimi Code，从开始菜单打开 "Ubuntu"（或者在 Windows Terminal 里新建一个 Ubuntu 标签页），cd 到项目目录后运行 kimi。

WSL 里怎么访问 Windows 的文件？ Windows 的 C 盘被挂载在 /mnt/c，比如 Windows 桌面上的文件在 WSL 里的路径是 /mnt/c/Users/你的用户名/Desktop/...。能用，但读写速度比 Linux 自己的目录（~，即 /home/你的用户名）慢不少，所以正式项目建议放在 Linux 主目录下。

2.5 Windows：用 PowerShell 安装（原生路线）

走这条路线有一个硬性前提：先装好 Git for Windows（见 2.1 节），因为 CLI 在 Windows 上依赖它自带的 Git Bash 作为 shell 环境。装好 Git 后，在 PowerShell 里粘贴下面这行命令，回车：

irm https://code.kimi.com/kimi-code/install.ps1 | iex

同样，等输出走完、没有报错就是装好了。

一般来说，安装程序能自动找到 Git Bash。但如果你把 Git 装在了自定义位置，首次运行 kimi 时可能会报找不到 shell 环境。解决办法是设置一个环境变量 KIMI_SHELL_PATH，指向 bash.exe 的绝对路径。图形界面操作路径是：设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 在"用户变量"里点"新建"——变量名填 KIMI_SHELL_PATH，变量值填 bash.exe 的完整路径（默认安装位置是 C:\Program Files\Git\bin\bash.exe），确定后重新打开 PowerShell。

2.6 验证、升级与卸载

不管走哪条路线，装完后都做同一件事：关掉终端窗口，重新打开一个（让 PATH 生效），然后输入：

kimi --version

显示出版本号（比如 1.x.x），恭喜，安装成功。

如果提示 command not found（Windows 上是"不是内部或外部命令"），先确认你确实重开了终端窗口；还不行的话，重新运行一遍安装脚本，仔细看输出末尾——它会告诉你 kimi 被装到了哪个目录，检查那个目录是否在 PATH 里。

以后升级：在终端里运行 kimi upgrade，它会检查最新版本并给出更新选项，选择"Install update now"即可。npm 安装的用户也可以直接运行 npm install -g @moonshot-ai/kimi-code@latest。

卸载：脚本安装的，删掉 kimi 可执行文件即可（安装路径在当初脚本的输出里）；npm 安装的，运行 npm uninstall -g @moonshot-ai/kimi-code。另外，Kimi Code 的本地数据（配置、会话记录、日志）统一存放在 ~/.kimi-code/ 目录下（Windows 原生路线是 C:\Users\你的用户名\.kimi-code\），想彻底清理就把它一起删掉。

2.7 登录：把 CLI 和你的 Kimi 账号连起来

装好了，先来登录。为了不弄乱你现有的任何文件，我们建一个专门的练习目录：

# macOS / Linux / WSL2
mkdir ~/kimi-playground
cd ~/kimi-playground

# Windows PowerShell
mkdir ~\kimi-playground
cd ~\kimi-playground

然后输入 kimi，回车。第一次启动时，界面会提示你配置 API 来源。在输入框里输入：

/login

注意斜杠不能少。回车后会出现一个平台选择器，提供两个选项：

• Kimi Code (OAuth)——推荐，用 Kimi 会员账号直接授权，就是第 1 章说的会员权益路线；
• Kimi Platform API key——用开放平台（platform.kimi.com / platform.kimi.ai）的 API Key 登录，那是按量计费的另一套体系。本教程全程用不上它。

用方向键选中 Kimi Code (OAuth)，回车。接下来是设备授权流程：终端里会显示一个链接，你用任意设备的浏览器打开它（手机浏览器也行），登录你的 Kimi 账号，然后按页面提示输入或确认授权码。授权成功后回到终端，CLI 会自动感知到，直接就能用了——不需要重启。

以后想退出登录或换账号，输入 /logout 即可，它会清除当前保存的凭证。

2.8 第一次对话

登录成功后，先认识一下你眼前的界面。Kimi Code 的界面（术语叫 TUI，终端用户界面）由三部分组成：

• 对话区（占绝大部分空间）：你和 Kimi 的聊天记录、它的工具调用过程都显示在这里；
• 输入框（底部）：你打字提需求的地方；
• 状态栏（最底下一行）：显示当前模型、目录、会话状态等信息。

现在，在输入框里输入你的第一句话，比如：

看一下这个项目的目录结构，简单介绍一下每个目录是干什么的

回车发送。因为练习目录是空的，它大概率会如实告诉你"这是个空目录"，并主动提议可以做点什么。注意观察对话区：它在回答之前会调用工具去真实地查看目录——它不是凭空想象，是真的去看了。

接着，试试让它动手：

帮我写一个 Python 的 Hello World 程序并运行一下

这次你会看到一个新东西：审批面板。当它要创建文件、运行命令这类"有副作用"的操作时，会停下来弹出选项征求你的同意，用方向键选择、回车确认（拒绝可以按 Esc）。而纯粹的只读操作（看文件、搜内容）默认是直接执行的，不会打扰你。这套审批机制是 Kimi Code 的重要安全设计，第 4 章我们会详细展开，现在先混个脸熟。

两个小提示：

• 任何时候输入 /help 可以打开内置的帮助面板，查看全部命令和快捷键，用 ↑/↓ 浏览，按 Esc 关闭。忘了什么就翻它。
• 想退出程序：输入 /exit，或者在空闲时连按两次 Ctrl-C，或者在输入框为空时按 Ctrl-D。

退出后如果想接着刚才的聊，在同一个目录里运行 kimi -c 就能恢复上次的会话。会话管理是第 5 章的主题，这里先知道有这回事。

本章小结

这一章我们完成了从零到手：

• 安装：macOS / Linux / WSL2 用一行官方脚本，Windows 原生用 PowerShell 命令（前提是先装 Git for Windows）；
• 验证与维护：kimi --version 验证，kimi upgrade 升级，本地数据都在 ~/.kimi-code/；
• 登录：/login 选择 Kimi Code (OAuth)，浏览器里完成授权即可；
• 第一次对话：认识了对话区、输入框、状态栏，体验了审批面板，学会用 /help 自助和正确退出。

环境已经就位，下一章我们正式开始实战项目：从零创建"体重管理小助手"，完成项目初始化、第一次提交，顺便把"动手先 git init"的习惯立起来。

04 实战起航-创建体重管理小助手

环境已经就绪，从这一章开始，我们正式进入实战。整个教程的剩下部分，我们都会围绕一个项目展开——体重管理小助手：它能记录你每天吃了什么（热量摄入）、运动了多少（热量消耗），还能跟踪体重的变化。

这不是一个程序员玩具，而是一个你打开浏览器就能用的网页应用。本章的目标是让它从 0 到 1：建好项目和 git 仓库、让 Kimi 生成一个能用的骨架、学会三个高频输入技巧、完成第一次提交。内容不少，但每一步我都会带着你做。

3.1 先想清楚做什么，再立下第一个规矩

动手之前，先把第一版的范围想清楚——这是跟 AI 协作的重要习惯：你得先知道自己要什么，才能判断它做得对不对。

先说技术方案。 我们采用纯前端路线：HTML + CSS + JavaScript 三件套，数据保存在浏览器的 localStorage 里，不引入任何框架、第三方库和后端服务。选它的理由很实在：

• 零依赖：不用装 Python、不用装 Node，有浏览器就能跑；
• 跨平台一致：macOS、Linux、Windows 上的表现完全相同，教程后面再也不用为运行环境分平台；
• 够用：一个个人使用的小应用，数据存在自己浏览器里，简单又私密。

再定第一版（v0.1）的范围，刻意做减法，只保留最小核心：记录某一天的体重（公斤）、按日期查看历史记录列表、刷新页面数据不丢。

接下来立第一个规矩：先 git init，再写代码。

# macOS / Linux / WSL2
mkdir ~/weight-tracker
cd ~/weight-tracker
git init -b main

# Windows PowerShell
mkdir ~\weight-tracker
cd ~\weight-tracker
git init -b main

为什么一行代码还没写就要初始化 git？因为 git 是你和 AI 协作时的"后悔药"。Kimi Code 干活又快又多，偶尔也会有你不满意的改动——只要每一步都有提交记录，改坏了随时能还原，你才敢放心放手让它做。先有版本管理，再谈大胆尝试。

如果你是第一次使用 git，顺手把身份信息配好（提交记录里要署名），把命令里的名字和邮箱换成你自己的：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

3.2 启动固定的本地页面地址

先确认 Python 可用：macOS/Linux python3 --version，Windows py --version。在项目目录另开终端运行 python3 -m http.server 8000 --bind 127.0.0.1（Windows 用 py -m http.server 8000 --bind 127.0.0.1）。保持该终端运行，结束时 Ctrl+C。后续始终使用同一浏览器的 http://127.0.0.1:8000，测试页为 /tests.html；不要混用 localhost、不同端口或 file://。

localStorage 按 origin 隔离，旧 file:// 数据不会自动迁移；先导出／抄录练习数据，再在新地址导入或重新录入。

页面操作 让 Kimi 生成项目骨架

确保终端当前就在 weight-tracker 目录里，输入 kimi 回车，然后把下面这段需求发给它：

我们来做一个网页版的体重管理小助手，这是第一版。要求：
1. 纯前端实现：index.html、style.css、app.js 三个文件，不引入第三方库和框架
2. 数据保存在浏览器的 localStorage 里，刷新页面不丢
3. 功能：记录某一天的体重（公斤）、按日期查看历史记录列表
4. 界面简洁清爽，附一个简短的 README.md 说明用法
创建好后告诉我怎么打开使用。

注意这段话的写法，它包含了"好需求"的三要素：目标（做什么）、约束（用什么技术、几个文件）、验收（怎么算完成）。以后你给它派活，都尽量把这三样说全，返工率会低很多。第 6 章我们还会专门练这个。

发送之后，盯着对话区看它是怎么工作的：它会先思考、列出步骤，然后开始调用工具创建文件。当它第一次要创建文件时，你会正式见到审批面板——上一章混过脸熟，这次仔细看：

• 面板里会写明它想做什么（比如"写入 index.html"），并给出几个选项，通常是：批准这一次、本次会话内对同类操作不再询问、拒绝；
• 用方向键移动选择，回车确认；也可以直接按数字键 1 / 2 / 3 快速选择；
• 想拒绝，按 Esc、Ctrl-C 或 Ctrl-D 都可以。

本章建议一律选"批准这一次"，把每一步都看清楚；至于什么时候可以放手让它自动跑，是下一章的主题。

骨架建好后，按它说的方式打开页面——使用前面启动的 http://127.0.0.1:8000/index.html。不要双击本地文件；可在终端用一行命令打开这个 HTTP 地址：

# macOS
open http://127.0.0.1:8000

# Linux
xdg-open http://127.0.0.1:8000

# WSL2（借用 Windows 的浏览器打开）
explorer.exe http://127.0.0.1:8000

# Windows PowerShell
start index.html

页面打开后，试着录入一条体重、刷新页面再看看——记录还在，说明 localStorage 持久化生效了。如果它生成的界面和我描述的不完全一样，别意外——AI 每次的实现细节可能不同，这是正常的，只要满足需求即可。

它的回复和你看到的不一样怎么办？ 本教程里所有的对话示例都是"示意"，你的实际输出不会逐字相同。判断标准不是"和书上长得一样"，而是"需求有没有被满足"。没满足就直接告诉它哪里不对，让它改。

3.3 输入技巧三连：@、/、!

骨架已经跑起来了，先别急着加功能。工欲善其事，必先利其器——我们来学三个几乎每天都会用到的输入技巧，它们能让你和 Kimi 的协作效率高一个档次。

@ 引用文件。 在输入框里输入 @，会触发文件路径补全，用方向键选中后回车，路径就插进你的消息里了。文件夹会以 / 结尾，选中后可以继续往里面补全。比如：

@app.js 给我讲讲这个文件的结构，每个函数是干什么的

它读到消息时会直接加载这个文件的内容，不用你手动复制粘贴代码。

/ 唤起命令。 输入 / 会弹出命令菜单，边输入边过滤，按 Esc 关闭。如果输入的内容不匹配任何命令，回车后会作为普通消息发给 Kimi，不会报错。记不住命令没关系，看到什么点什么就行。

! 进入 Shell 模式。 在空输入框里输入 !（或直接粘贴一条以 ! 开头的命令），输入框左边的提示符会变成 !、边框变成紫色——这表示进入了 Shell 模式，可以直接跑终端命令，比如：

!git status

Shell 模式有两个妙处：一是命令的输出会写进对话上下文，Kimi 之后能看到结果，你可以紧接着问"上面这个输出是什么意思"；二是全程不用离开对话。命令执行完会自动回到正常模式（在空输入框按 Backspace 或 Esc 也可以退出）。如果命令跑得很久，按 Ctrl+B 可以把它转为后台任务，不阻塞你继续聊。

再补两个零碎但实用的：写长需求时用 Shift + Enter（或 Ctrl + J）换行；输入框为空时按 ↑/↓ 可以翻阅历史输入。

3.4 第一次提交

到这里，第一版应用已经能跑能用了，但眼下的成果还只是散落在目录里的几个文件，该把它们郑重地收进 git 了。提交之前，先补一个 .gitignore——让 Kimi 来：

帮我创建一个 .gitignore，忽略各操作系统的垃圾文件，比如 macOS 的 .DS_Store、Windows 的 Thumbs.db

我们的数据存在浏览器 localStorage 里，仓库里天然没有隐私数据，这一点很省心。不过要记住一个对应关系：数据跟着浏览器走，代码跟着 git 走——换一台电脑，拉下代码就能继续开发，但体重记录不会跟过去（第 6 章我们会给应用加数据导出功能来解决这个问题）。

然后，提交也交给它：

帮我完成第一次 git 提交。提交信息遵循「类型: 简述」的格式，这次用 feat 类型

审批它的 git add 和 git commit 操作，完成后用 !git log 看一眼成果——第一次提交就这样诞生了。

顺便把"小步提交"的理念说透：每完成一个能用的小版本，就提交一次。 不要攒了一堆改动再提交——提交越频繁，每个提交越纯粹，出问题时越容易定位和回退。这个习惯会在后面的章节里反复实践。

本章小结

这一章我们的项目正式起航了：

• 定下技术方案：纯前端网页应用（HTML + CSS + JS + localStorage），零依赖、跨平台一致；
• 立下第一个规矩：先 git init 再写代码，git 是你和 AI 协作的后悔药；
• 用"目标 + 约束 + 验收"三要素描述需求，让 Kimi 生成了能用的项目骨架，并完整体验了审批面板的操作；
• 学会了三个输入技巧：@ 引用文件、/ 唤起命令、! 进入 Shell 模式；
• 完成了第一次提交，并理解了"小步提交"的原则。

目前的 Kimi 每做一件事都要你点头，安全是安全，但你可能已经开始觉得"有点黏人"了。下一章我们就来解决这个问题：三种权限模式怎么选、什么时候可以放心放手，以及对付复杂任务的大杀器——Plan 模式。

05 权限模式与计划模式

上一章里，Kimi 每创建文件、每跑一条命令都要弹窗问你，一路点头下来，安全是安全，但你大概也感觉有点黏人了。反过来，完全不管也不行——它毕竟能改文件、能跑命令，真放飞了你也睡不着。

这一章解决的就是"控制"问题：什么任务该管严、什么任务可以放手（三种权限模式）；复杂任务怎么先审方案再动手（Plan 模式）；以及它干活的中途，你还能做哪些操作（过程控制）。

4.1 三种权限模式：什么任务，配什么信任级别

先打个比方。Kimi Code 像你带的一位能力很强的同事，而权限模式就是你给他的信任级别：新人入职时事事汇报，合作久了可以例行放权，只有在完全输得起的环境里才敢彻底不管。

Kimi Code 提供三档，随时切换：

Always Ask 是你已经在用的模式，不再多说。重点看后两档。

Ask When Needed（/yolo） 是最实用的放权档位：常规的文件修改、命令执行不再逐项打扰你，效率明显提升。但它不是无条件放行，以下几类情况仍然会征求你的同意：

• 访问敏感文件，比如 .env、SSH 私钥；
• 执行危险命令，比如 rm -rf、shutdown；
• 退出 Plan 模式（下一节细讲）。

而且它只是"少问"，不是"不问"——它拿不准需求时，仍然会主动向你提问。所以像"把所有页面里的重复样式合并到 style.css，改完打开页面确认没变形"这种边界清楚、结果可验证的批量任务，用 /yolo 非常合适。

Never Ask（/auto） 是完全托管：所有审批自动通过，包括敏感文件和 Plan 退出，它也不会再向你确认任何事，连 rm -rf 这类危险命令的保护网都会撤掉。请把这句话刻在心里：只在你完全输得起的环境里用它——比如一次性容器、虚拟机、或者刚刚提交过、随时能还原的仓库。日常开发不要开。

切换方法：在输入框输入 /yolo 或 /auto 回车（它会打开权限模式列表并预选对应档位，确认即生效）。

我们的实战建议：平时待在默认模式，遇到明确安全的大批量任务切 /yolo，/auto 暂时忘掉它。 等第 8 章讲脚本化和自动化时，你会更理解什么时候才轮到它出场。

4.2 Plan 模式：复杂任务，先审方案再动手

权限模式管的是"执行时的松紧"，Plan 模式管的是"动手前的章法"。

有些任务你直接让它干，它也能干完，但过程可能跑偏：改了你不想改的文件、用了你不喜欢的方案。Plan 模式就是为此准备的——它先输出一份行动计划，等你审阅批准后才动手。适合改动较大、方向没把握、或者你想看看它思路的任务。

切换方式：按 Shift-Tab，或者输入 /plan。

现在实战。我们来给体重管理小助手加第二个功能：每日热量预算。先切到 Plan 模式（按 Shift-Tab，界面上会有模式标识），然后发送：

我想给应用加一个新功能：每日热量预算。
1. 页面上可以设置每天的热量目标（千卡），目标要持久保存
2. 每餐可以录入热量，比如"午饭 650 千卡"，按天汇总
3. 页面上能直观看到今天已摄入多少、距离目标还剩多少
先别动手，给我一个实现计划。

这次它不会直接写代码，而是输出一份计划：打算改哪些文件、分几步做、每步做什么。仔细看这份计划——审核计划比审核代码省力气，方向不对在这里拦下成本最低。 看完你有三种选择：

• 批准：它就按计划开工；
• 拒绝：它收手，你可以换个提法重来；
• 要求修改：直接说出你的意见，比如"热量目标和体重记录放在同一个数据对象里，不要搞两套存储"，它会修订计划再给你看。

批准后它开始实现。完成后验证一下：刷新页面，把每日目标设为 1800 千卡，录入"早餐 400 千卡""午餐 650 千卡"，看看剩余额度算得对不对、刷新后数据还在不在。一切正常后，提交：

功能完成了，帮我提交这次改动，提交信息还是用「类型: 简述」格式

回顾刚才的过程：先出计划 → 审计划 → 实现 → 验证 → 提交。这就是一个规范的开发闭环，哪怕是一个人加一位 AI 的小项目，也值得这样走。以后每加一个功能，我们都走这个流程。

两个补充说明：/plan clear 可以在空闲时清除当前计划，重新开始规划；另外，退出 Plan 模式永远需要你确认——即使开了 /yolo 也不例外，这是防止"计划没审完就开干"的最后一道闸。

4.3 过程控制：它干活时，你还能做什么

Kimi 一旦开始输出，并不是"只能干等"。这几个按键让你随时介入：

Esc / Ctrl-C：打断当前回合。 发现它方向不对、或者你想换个说法，立即打断。注意区分：打断的是"当前这一轮输出"，不会退出程序；只有空闲时连按两次 Ctrl-C 才是退出。

Ctrl-S：中途插话。 它输出到一半，你突然想到要补充——不用等它说完，在输入框里把话打好，按 Ctrl-S，这句话会立刻注入当前回合，它马上就能看到并作出调整。比如它正在写页面，你插一句"配色清淡一点，不要用大面积深色"。

Ctrl+B：转后台。 Shell 模式里跑的命令太久，按 Ctrl+B 把它转为后台任务，你可以继续聊别的，它跑完会通知你。

Ctrl-O：折叠/展开输出。 工具输出太长刷屏时，用它把输出卡片折叠起来，界面立刻清爽；想看细节再展开。

/undo：收回最近的输入。 话说出口发现不对，用它撤销最近的 prompt 重来。

这些按键不用刻意背，记住"它干活时我也能说能停"这个感觉，用两次就形成肌肉记忆了。忘了就 /help 翻一翻。

本章小结

这一章我们学会了和 Kimi 相处的"分寸感"：

• 三种权限模式：默认的 Always Ask 逐项确认；/yolo 放权常规操作但守住敏感文件和危险命令；/auto 完全托管，只在输得起的环境用；
• Plan 模式（Shift-Tab / /plan）：复杂任务先审计划再动手，并用它实战了"每日热量预算"功能，走了一遍"计划 → 实现 → 验证 → 提交"的开发闭环；
• 过程控制：Esc/Ctrl-C 打断、Ctrl-S 插话、Ctrl+B 转后台、Ctrl-O 折叠、/undo 收回输入。

到这里，单次对话内的操作你已经很熟练了。但一个项目是要做好多天的——关掉终端、明天再开，怎么接着干？聊到一半想开个新方向试试怎么办？下一章我们学会话与上下文管理，让项目可以"跨天续命"。

06 会话与上下文管理

到目前为止，我们的工作都发生在"一次对话"里。但真实的项目是要做好多天的：晚上关掉终端，明天早上接着干；聊了一个小时，上下文越积越多；聊得好好的，突然想试试另一个方向……这些都要靠会话管理来解决。

这一章学四件事：会话的保存与恢复、上下文压缩、会话分叉、会话导出。学完后，你和 Kimi 的协作就从"一次性聊天"升级成了"可持续的项目搭档"。

5.1 会话就是存档，而且会自动保存

先建立一个关键认知：每一次对话都会自动保存为一个"会话"（session），存在本地 ~/.kimi-code/sessions/ 目录下，并且按工作目录分组——你在 weight-tracker 里聊的内容，和在别的目录里聊的内容，各存各的，互不干扰。你不需要手动保存任何东西，反过来，也不要去手动修改 sessions 目录里的文件，那可能导致会话无法恢复。

基于这个机制，常用的操作是这些：

接着上次干。 在 weight-tracker 目录里运行：

kimi --continue

就会恢复这个目录下最近的会话，之前的对话上下文原封不动。简写是 kimi -c。你可以现在就试试：退出 Kimi（/exit），重新运行 kimi -c，看它是不是还记得我们的体重管理项目。

浏览历史会话。 两种入口：终端里运行 kimi --session（不带参数会进入交互式列表），或者在会话中输入 /sessions（别名 /resume），用方向键挑选、回车进入。想直达某个会话，用 kimi --session <会话ID>。

给会话起名。 会话多了以后，列表里全是一串 ID 可不好认。输入：

/title v0.2-每日热量预算

给当前会话起个好认的名字（别名 /rename；不带参数时显示当前标题）。

开新会话。 输入 /new（别名 /clear）。什么时候该开新的？记住一个原则：话题切换就开新会话。上下文是 Kimi 的记忆也是它的注意力——里面堆着无关内容，它反而容易分心。同一个功能接着聊，换个功能换个话题，就 /new 一下。

5.2 上下文压缩：/compact

聊得越久，上下文就越长。接近模型上限时，Kimi Code 会自动压缩历史消息腾出空间，但自动压缩的时机未必合你意，所以你也可以随时手动来一下：

/compact

还可以带一句提示，告诉它压缩时重点保留什么：

/compact 保留关于数据存储结构的讨论和尚未完成的任务

什么时候压缩？可以类比 git commit 的时机：一个阶段性工作收尾时。比如刚完成"每日热量预算"功能、准备开始下一个功能，先 /compact 一下，把前面的讨论浓缩成摘要，轻装上阵。

而如果你要切换到完全不相关的任务，就别压缩了，直接 /new——压缩是为了"接着做"，新会话是为了"换着做"。

5.3 /fork：给会话开一个"分支"

/fork 分叉对话，但仍可能操作同一目录。实验前确认工作已提交，在终端运行 git worktree add -b experiment/theme ../weight-theme HEAD，再到新目录启动 Kimi。

喜欢结果时提交并在主目录合并该分支；不满意时先查看实验目录的 git status --short、git diff 和 git diff --cached，保存仍有价值的内容，再由你决定是否删除实验副本。git restore . 只恢复已跟踪文件的未暂存修改，既不撤销暂存，也不删除新文件。

会话 fork、分支、worktree 分别管理对话、提交历史和文件工作目录，不应互相替代。

5.4 导出会话：存档与分享

有些对话值得留下来：一次精彩的排错过程、一段重要的方案讨论。在会话中输入：

/export-md

就能把当前对话导出成一份可读的 Markdown 文件（别名 /export；可带路径参数，不带就写到当前目录，文件名类似 kimi-export-a1b2c3-20260923.md）。我们之前给界面定方案的讨论，就可以导出存进项目的 docs/ 目录，作为"设计决策记录"——这是很多专业团队都在用的习惯。

如果是遇到了程序异常、需要反馈问题，则在终端里用 kimi export <会话ID>，它会把会话打包成 ZIP（含诊断日志），方便提交给官方排查。

分享前检查一下内容。 导出的文件里可能包含代码、命令输出、文件路径等敏感信息，发给别人之前先翻一遍。

本章小结

这一章让项目具备了"跨天续命"的能力：

• 会话自动保存、按工作目录分组；kimi --continue 接着上次干，/sessions 浏览历史，/title 起名，/new 开新话题；
• 阶段性收尾用 /compact 压缩上下文，换任务用 /new 开新会话；
• /fork 分叉会话做零成本实验，记住对话分叉归 fork，代码后悔归 git，两者搭配使用；
• /export-md 导出对话存档，重要讨论留作设计记录。

工具层面的基本功到这里就齐了。下一章是全书的核心章：我们回到项目本身，完整走几遍专业的开发流程——写清需求与验收标准、给应用配测试、用正确的方法修 bug、放心大胆地重构，以及 git 分支与项目文档。

07 功能开发全流程

前五章我们学的都是"怎么用 Kimi"，这一章回到项目本身。我们会连续走几遍专业开发的完整流程：提清需求 → 实现 → 测试 → 修 bug → 重构 → 分支管理。这一章是全书的核心，篇幅也最长，建议分几次读完——更重要的是跟着做，做一遍比读三遍都管用。

6.1 写好需求：功能描述 + 验收标准

先说一个新手最常踩的坑：把需求写成一句话，比如"给我的应用加上饮食记录"。Kimi 确实会干活，但做出来的东西十有八九和你想的不一样——它不知道你要记哪些字段、不知道新功能和已有的"热量预算"是什么关系、更不知道你打算怎么验收。AI 不会读心术，需求里的每一分模糊，都会变成返工。

专业的写法是功能描述 + 验收标准清单。现在实战，给应用加两个大功能：结构化的饮食记录和运动记录。发送：

给应用加两个功能：饮食记录和运动记录。

饮食记录：
1. 每餐记录包含：餐别（早/午/晚/加餐）、食物名称、热量（千卡）
2. 之前"每日热量预算"里手工录的热量输入，迁移为这里的饮食记录

运动记录：
1. 每条记录包含：运动项目、消耗热量（千卡）
2. 运动热量计入当天总消耗

首页按天汇总显示：今日总摄入、总消耗、净摄入（摄入减去消耗）。

验收标准：
1. 刷新页面数据不丢
2. 首页能看到今日摄入、消耗、净摄入三个数字，且数值计算正确
3. 浏览器窗口拉到手机那么窄时，页面也能正常显示和操作

对比第 3 章的需求，这次多了两样关键东西：

• 和旧功能的关系："手工录热量迁移为饮食记录"——不说清楚，它很可能给你留两套并存的录入入口，数据各算各的；
• 可逐条检查的验收标准：它既是你验收时的对照表，也是 Kimi 完工前自查的依据。

它做完后，逐条核对验收标准：刷新页面看数据还在不在、心算核对三个汇总数字、把窗口拉窄试试布局。如果哪条没通过，不要自己动手改代码，直接把事实甩给它：

验收标准第 2 条没通过：我录了早餐 400、午餐 650，
首页总摄入显示 900，应该是 1050。请修复。

发现它对需求的理解有偏差，也一样处理——在对话里说清楚哪里不对、应该是什么样，让它改到你满意为止。**你的角色是产品经理加验收员，不是替它擦屁股的实习生。**全部通过后，提交。

6.2 给它配上测试：零依赖的测试页

功能多了，"每次手动点一遍验证"会越来越靠不住：点一遍要五分钟，而且人总会偷懒漏项。该上测试了。

但我们的项目没有 Node 环境，怎么跑测试？用一个零依赖的办法：**把计算逻辑抽成独立模块，再写一个浏览器里直接打开的测试页。**发送：

把热量汇总、净摄入这类纯计算逻辑抽到一个独立的 calc.js 里，
然后写一个 tests.html 测试页：浏览器打开它就能看到每条测试是否通过（绿色通过、红色失败）。
覆盖这些场景：单日汇总、多条记录累加、净摄入计算、空数据、边界日期。

这个方案能成立，关键在于"纯计算逻辑"——也就是纯函数：给它输入，它算出输出，不碰页面、不碰存储。这种函数最好测，扔几组数据进去，对一下结果就行。反过来，如果计算逻辑和界面操作混在一起，想测都无从下手。所以"把纯逻辑抽出来"本身就是一次小小的架构改善。

完成后打开 tests.html（保持第 3 章 HTTP 服务运行，访问 http://127.0.0.1:8000/tests.html）。页面会列出每条测试的名称和结果，全绿才允许提交。

如果有红色条目怎么办？把那条测试的名称和失败信息原样发给 Kimi：

tests.html 里"净摄入计算"这条失败了，期望 -300，实际显示 NaN，请修复。

它修完你刷新页面再看，直到全绿。

从此立个新规矩：**每次改动计算逻辑，先开测试页跑一遍。**测试不是为了形式，是为了让后面的每一次修改都有底气。

6.3 修 bug 的正确姿势

先说方法论。向 Kimi 报 bug，一次给清三样东西：症状、复现步骤、期望行为。对比两种报法：

• 差的报法："应用有点问题，数字不对，你看看吧。"——它得来回追问三轮才能开工。
• 好的报法，看下面这个完整示例：

症状：首页的"今日总摄入"没算上加餐。
复现：1. 录一条"加餐，苹果，95 千卡"；2. 回到首页看今日总摄入。
期望：总摄入应该包含加餐的 95 千卡；实际：数字没有变化。

如果原因不明，就让它先调查后动手：

先别改代码。请找出最可能的原因，列出可疑的文件和位置，我确认方向后你再动手。

这样可以避免它一边猜一边改，把代码搅得更乱。

光说不练假把式，来场排错演习：

我们做个练习：请在 app.js 里故意引入一个会导致日期判断出错的 bug，
不要告诉我细节，然后等我报 bug。

接下来按真实流程走一遍：

1. 观察现象：在浏览器里正常操作应用，留意哪里不对劲（比如昨晚录的记录跑到了今天）；
2. 记录复现步骤：把"做了什么操作、看到什么"一步步记下来，确保按这个步骤能稳定重现；
3. 按模板报给它：不偷看代码，只描述症状、步骤、期望；
4. 双确认验收：现象消失 + 测试页全绿，才算修完；
5. 提交，提交信息用 fix: 类型。

这个演习值得认真做——真实工作中遇到 bug 时，流程一模一样，区别只是没人陪你排练。

6.4 重构：敢改，因为有测试和 git 兜底

代码越攒越多，app.js 开始变得臃肿：数据读写、计算调用、界面操作全搅在一起。该重构了。重构的黄金法则是不改变外部行为，只改善内部结构——而我们的测试页和 git，正好为这个法则上了双保险。

切到 Plan 模式（还记得吗，复杂任务先审方案），发送：

app.js 现在有点臃肿了。请重构一下：
1. 把数据读写（localStorage 相关）抽到 storage.js
2. 计算逻辑已经在 calc.js 了，app.js 只保留界面交互
3. 不改变任何现有功能的表现
先给我一个重构计划。

审重构计划时多留个心眼：警惕"顺手改行为"。如果计划里出现"顺便把汇总逻辑改成……""顺便优化一下显示格式"之类的条目，让它拿掉——重构就只做结构调整，行为变更另起一次改动；混在一起做，出了问题根本没法定位。一份合格的重构计划，还应该写清楚"如何验证行为不变"。

批准、它动手。改完后双验证：测试页全绿 + 手动把核心流程过一遍（录体重、录餐、录运动、看汇总、刷新）。都正常，提交（refactor: 类型）。

体会一下这个安全感：测试页兜住"行为没变"，git 兜住"随时可退"，所以重构从一件提心吊胆的事，变成了一件日常小事。这就是好习惯的复利。

6.5 Git 分支与项目文档

我们的提交一直打在主分支上，单人项目这样问题不大。但当你要做一个"可能会失败"的尝试时，开个分支更稳妥：

git switch -c feature/weekly-report   # 创建并切到功能分支

分支上随便折腾，满意了切回主分支合并：

git switch main
git merge feature/weekly-report

不满意时先检查实验目录的暂存、未暂存和未跟踪文件，保存要留的改动。已提交未合并的分支会被 git branch -d 拒绝删除；保留分支也可以安全回到主线。只有确认不再需要其提交时才用 git branch -D feature/weekly-report。分支本身不是文件隔离，建议沿用第 5 章的独立 worktree。

顺便把提交信息的类型规范补全，以后照着用：

文档也该跟上。让 Kimi 来：

根据 git log 里的提交记录，生成一份 CHANGELOG.md，按 feat / fix / refactor 分类；
再把 README.md 更新一下，功能列表要包含现在的全部功能

养成"功能做到哪，文档跟到哪"的习惯，三个月后的你会感谢现在的你。

动手练习：数据导出与备份

还记得第 3 章埋的伏笔吗——数据跟着浏览器走，换电脑就丢。现在你自己走一遍完整闭环，给应用加上"导出 / 导入"功能。提示：

1. 自己写需求：导出为 JSON 文件下载、选择 JSON 文件导入恢复；
2. 自己写验收标准（至少包括：导出后清空数据、再导入、记录完整恢复）；
3. 复杂任务记得 Plan 模式先行；
4. 完成后跑测试页、提交。

完整做完这个练习，你就把本章的流程内化成自己的了。

本章小结

这一章我们完整走了一遍专业开发流程：

• 需求写成"功能描述 + 验收标准清单"，交代清楚与旧功能的关系；验收没通过就摆事实让它修，你的角色是产品经理加验收员；
• 用"独立计算模块 + 浏览器测试页"的办法，给零依赖项目配上了测试，全绿才允许提交；
• 报 bug 给齐"症状、复现、期望"三样，原因不明就先调查后动手；
• 重构只做结构调整、警惕顺手改行为，有测试和 git 双兜底就敢放手做；
• 实验性开发开 git 分支，提交信息按类型规范书写，文档跟着功能走。

应用的功能已经像模像样了，但录入数据还得手工填——吃个苹果都要自己查热量，太麻烦。下一章我们给 Kimi 接上"眼睛"和"网络"：让它联网查热量、看照片估热量、按截图改界面。

08 联网与多模态实战

我们的应用现在功能齐全，但用起来有个明显的麻烦：录一顿饭，得自己先查好热量再手工填进去。吃个苹果都要开搜索引擎，太反人性了。

这一章给 Kimi 接上两种"感官"：联网搜索（它能自己上网查资料）和多模态输入（你可以直接贴图片、贴视频给它看）。我们的应用会因此好用一大截。

7.1 联网搜索：给应用建一个食物热量库

Kimi Code 不是只能在本地打转——它能联网搜索关键词、抓取网页内容。这意味着"查热量"这种活儿可以直接外包给它：

联网查一下常见食物的热量数据，整理 20 种左右中国人日常吃的食物
（米饭、面条、鸡蛋、鸡胸肉、苹果、牛奶……），生成一个 foods.js 文件：
一个数组，每项包含名称、熟/生状态、可食部单位、来源链接、查询日期和每 100 克的热量 kcal_per_100g。
然后在饮食记录的表单里加一个"热量速查"下拉框：
选中食物后输入食用克重 grams（正数），以 kcal_per_100g * grams / 100 计算本条记录的总千卡；保存克重、单位和状态，不把每100克值直接当整餐总量。

发送后观察它的工作过程：它会先搜索，再抓取几个网页的内容，交叉比对后整理成数据文件，最后改表单。整个过程可能要一两分钟——比你自己开二十个网页标签查快多了。

但这里要建立一个重要心态：**联网查来的数据要抽查，不能照单全收。**抽查的方法很简单：挑两三种你熟悉的食物，自己搜一下看数量级对不对。给你两个常识锚点：米饭大约 116 千卡/100 克，鸡蛋大约 140 千卡/100 克（约合 70 千卡一个）。如果它整理的数据明显偏离，直接指出来：

请核对 foods.js 中米饭的熟/生状态、每100克单位及数据来源；不能用熟饭的数量级判断生米数据错误。

另外，食物热量本来就是近似值——同样是米饭，软硬不同热量就差不少——所以应用里显示成"约 116 千卡"比写一个假装精确的数字更诚实。顺手让它把这个"约"字加上。

完成后老规矩：跑测试页、手动录一餐试试速查下拉好不好用、提交。

7.2 前置：打通文件与浏览器的数据通道

先让 Kimi 为页面实现“导出 JSON／导入 JSON”：导出全部练习记录到 records-export.json；导入时验证 schemaVersion、日期、正数克重、非负有限热量及唯一 ID，预览新增记录并在用户确认后写 localStorage。不要覆盖其他记录，重复 ID 拒绝并提示。文件位于本机，默认不提交 Git。

把导出的文件复制到项目 private-data/ 并加入 .gitignore。CLI 只读写该目录里的 JSON，浏览器仍由用户导入；第 8 章定时周报只能读取最近一次手动导出的文件，报告需注明导出时间，不能声称已自动读取浏览器实时数据。

图片练习 粘贴图片：拍张照片就能记热量

Kimi Code 的输入框不只能打字，还能直接粘贴图片。操作很简单：

• macOS / Linux：复制图片后，在输入框里按 Ctrl-V；
• Windows：按 Alt-V。

粘贴后输入框里会出现一个占位符，你可以像编辑普通文字一样调整它的位置、在它前后继续打字；发送时占位符才会被替换成实际内容。

先排一个新手几乎必踩的坑：**在文件夹里"复制"一个图片文件，粘贴进去的往往只是文件路径，不是图片本身。**正确的做法是让剪贴板里装着图片数据：macOS 用"预览"打开图片后按 Cmd+C，Windows 用"照片"应用打开后点复制按钮，网页上的图片直接右键选"复制图片"，或者干脆截图（截图天然就是图片数据）。

实战一：拍照记热量。 用手机拍一张你的午餐，把照片传到电脑（微信文件传输助手、邮件、数据线都行），打开图片复制，粘贴到输入框，附上一句：

估算照片中各食物的份量与热量范围，列出不确定性，先生成待确认的 meal-import.json；不要声称已写入浏览器记录。

它会分析照片里有什么菜、按菜色和分量估算热量，然后生成待导入文件。你确认份量后，通过页面导入按钮写入记录，并刷新核对。如果估得明显离谱——比如把你的一大碗面看成了一小碟——直接纠正它："这份面其实有两人份，重新估。"当然得说句实话：AI 看照片估热量是"参考级"的，图个方便快捷可以，真拿它当医学级依据就不必了。

实战二：按截图改界面。 看到喜欢的网页设计，截个图贴给它：

参考这张截图的风格，把我们应用的首页改成卡片式布局，配色清淡一些

它会分析截图的布局、配色、间距，然后动手改造。改完在浏览器里看效果，不满意就继续用嘴调整，像指挥一位设计师：

卡片之间的间距再大一点，标题字号小一点，热量数字用更醒目的颜色

两个注意事项：

• **多模态能力依赖当前模型。**登录 Kimi Code 账号后默认开启；如果粘贴时提示"当前模型不支持图片输入"，用 /model 换成支持图片输入的模型即可。
• **媒体有总量限制。**一个会话里图片视频累计超过 20MB，最旧的会被自动省略（界面上会有警告）。聊了大量图片后它"看不清"早期的图，就是这个原因——所以重要的结论，及时让它落成代码或文字，别只留在图片里。

7.3 粘贴视频：让它"看"一段操作

图片之外，它还能看视频——这是 Kimi Code 很有特色的能力。粘贴方式和图片完全一样，只是要求当前模型支持视频输入。注意，部分模型不支持视频（比如 256K 上下文版本），粘贴失败时 /model 换个模型再试。

拿我们的应用做个实战：把你操作应用的过程录一段屏——macOS 按 Cmd+Shift+5 可以录屏，Windows 按 Win+Alt+R 用游戏栏录制，也可以直接用手机拍电脑屏幕。录一段"录入一顿晚餐并查看今日汇总"的完整操作，贴给它：

看看这段操作录像，从用户体验的角度找出三个可以改进的交互细节，列给我

它会看完视频给出一份改进清单——可能是"录完一餐没有任何成功提示""删除记录没有二次确认""表单提交后输入框没有清空"之类你自己早就麻木了的细节。挑你觉得最值得改的一两条，让它顺手改掉，跑测试、提交。

体会到这一章的意义了吗？过去你要把问题"翻译"成文字描述给它；现在，你眼睛看到的，它基本都能直接看。沟通的带宽完全不一样了。

本章小结

这一章给 Kimi 接上了"感官"：

• 联网搜索：它能自己查资料，我们用它建了食物热量库和"速查"下拉；记住联网数据要抽查，数据不对就指出具体条目让它修；
• 粘贴图片（macOS/Linux Ctrl-V，Windows Alt-V）：拍照估热量写入记录、按截图改界面；注意剪贴板里必须是图片数据而非文件路径；能力依赖模型，媒体累计上限 20MB；
• 粘贴视频：录屏让它分析操作、挑交互毛病，从"你描述给它听"升级为"它自己看"；部分模型不支持视频输入。

到这里，应用已经相当好用了，但还差最后一环：坚持。体重管理贵在持续记录，而下章要讲的自动化正好解决这个问题——让 Kimi 每天提醒你记录、每周帮你生成周报，顺便把目标模式和脚本化这两个进阶能力一起拿下。

09 目标模式定时任务与脚本化

到目前为止，你和 Kimi 的合作模式都是"你一句、它一步"：你提需求，它执行，做完了等你下一句。这是最好的学习方式，但还差最后一层进阶——让它自己盯着目标往前跑，到点自动干活，甚至嵌进你的脚本里。

这一章拿下三个进阶能力：/goal 目标模式、定时任务、kimi -p 非交互模式。学完后，体重管理这件"贵在坚持"的事，Kimi 会帮你一起坚持。

8.1 /goal 目标模式：说清终点，让它自己跑

先体会两种派活方式的区别：

• 普通对话是"说下一步"："把这条失败的测试修好。"——它修完就停，等你下一句；
• 目标是"说终点"："修好所有失败的测试，并保持测试页全绿。"——它修完一条会自己找下一条，遇到障碍自己想办法，直到终点达成，或者实在走不下去向你报告。

这个能力叫 Goal 模式，用 /goal 开启，后面跟目标描述（最长 4000 字符）。写好目标的关键是终点必须可验证。对比：

• 坏目标："把应用做好。"——没有客观标准，它要么立刻卡住，要么无限期瞎忙；
• 好目标："修好 checkout 流程的所有回归 bug，每个修复都补上测试，最后跑通整个测试套件。"——"测试全绿"就是明明白白的终点线。

现在实战。先造一个需要持续追踪的场景：

使用配套 revision-assets/goal-lab 的独立副本。
先运行 node --test goal-lab.test.cjs，记录三个失败；不要改测试。
只允许修改 goal-lab.cjs，修复 BMI 平方分母、净摄入减法、空数组求和。

此选修需要 Node.js 22+。在独立副本运行 node --test goal-lab.test.cjs，确认三项失败后再启动目标；与主应用 tests.html 分开：

/goal 只修改 goal-lab.cjs，把 node --test goal-lab.test.cjs 的三个固定失败修好；测试通过后停止，不修改主应用或测试。
不许为了通过测试而改测试代码本身。

然后你就可以放松看着了：它会自己读代码、定位错误、修复、请你刷新测试页确认（或者自己想办法验证），一条接一条，直到全绿。中途它会停在一些需要你确认的地方（默认权限模式下审批照常进行），但它不会再问"接下来做什么"——这是和日常对话最本质的区别。

目标运行期间，常用这些管理命令：

一个目标以三种方式结束：complete（达成，它会给你一份总结）、paused（你暂停了它，或出了错）、blocked（它判断照现状走不下去，会写一段话解释原因——看到 blocked 别慌，读它的说明，往往是你需要补充信息或调整目标表述）。

什么时候用 Goal？记住一个判断标准：有明确终点线、且达成与否可验证的任务。修一批失败测试、追一个构建错误、完成一组边界清楚的改动，都很合适。反过来，"帮我看看这个项目"这种开放式探索、一次性的问答，用普通对话就好。

8.2 定时任务：让它到点提醒你

体重管理最大的敌人是"忘了记"。Kimi Code 可以在会话里设置定时任务：你只需用自然语言说出来，它会换算成调度规则，到点自动提醒你。

在会话中直接说：

每天早上 8 点提醒我在应用里记录体重；
每周五下午 5 点提醒我导出一次数据备份；
每周日晚上 8 点根据本周的记录，给我写一段饮食和体重的周回顾。

它就会为你创建这些定时任务。想确认当前有哪些任务在排队，问一句"我设了哪些定时任务"就行；想取消，直接说"取消每天早上 8 点的提醒"。

几个必须知道的规则，免得产生误解：

• 定时任务绑定在它所属的会话上。关掉终端没问题，下次用 kimi --session 恢复同一会话，任务会重新加载、继续触发；但新开的会话不会继承这些任务。
• 周期性任务（比如"每天早上"）7 天后会过期：第 7 天它最后一次触发时，会根据你当初的意图决定是否续期。所以长期任务到期时留意一下它的提示。
• 它会在会话空闲时触发提醒——如果你正在跟它聊别的，提醒会等这一回合结束再插入。

有了这三个提醒，你的"坚持记录"就有了外挂：早上称完体重有提醒，周五自动想起备份，周日晚上收到一份本周回顾。

8.3 kimi -p：把 Kimi 装进脚本里

前面所有用法都是"交互式"的——打开界面，你来我往。但还有一大类场景根本不需要对话：你已经明确知道要干什么，只想让 Kimi 干完就走。这时用 -p 参数：

kimi -p "看一下这个项目的目录结构，简要说明每个目录是干什么的"

它在终端里直接输出结果，然后退出，不进入交互界面。这一下就打开了新世界的大门：Kimi 可以被别的脚本调用了。

举两个贴近生活的例子。

**例一：每周生成项目进展小结。**在第 6 章的功能分支上我们做过周报功能，现在用另一种方式——让 Kimi 直接读 git 历史生成总结：

kimi -p "读取本仓库最近 7 天的 git 提交记录，按 feat / fix / refactor 分类，生成一份中文进展小结，保存为 weekly-report.md"

把它写进一个脚本文件（比如 weekly.sh，Windows 用户写成 weekly.ps1），每周日跑一下，或者交给系统定时器（macOS/Linux 的 cron、Windows 的任务计划程序），你就有了一个自动化的项目周报。

**例二：快速分析一堆文件。**假设你下载了一个月的健身 App 导出数据，堆在一个文件夹里：

kimi -p "分析 data 文件夹里所有的 CSV 文件，统计每周的平均体重和总运动消耗，输出成一个 Markdown 表格，保存为 summary.md"

一条命令，代替你打开每个文件手动汇总。

非交互模式的几个要点：

• 审批：交互模式下的审批面板在 -p 里照样生效，只不过变成了终端里的文字提示。生产环境的脚本里，权限模式要慎重选择（回顾第 4 章的建议）。
• 退出码：脚本里可以靠退出码判断结果——目标模式下的退出码是 0（完成）/ 3（blocked）/ 6（paused），方便脚本做分支处理。
• 组合技：-p 和定时任务可以配合——比如让定时任务"每天跑一次某条 -p 命令"，就是一套完整的无人值守自动化。

学完这一章你会发现，Kimi Code 的三层用法正好对应三种协作深度：交互模式是面对面讨论，目标模式是交代任务让它独立执行，脚本化是把它变成你工具链里的一个零件。什么时候用哪层，取决于任务的开放程度和你的信任程度。

本章小结

这一章我们完成了从"你催它做"到"它自己做"的进阶：

• /goal 目标模式：说清可验证的终点线，它自己规划、自己执行、遇到障碍自己想办法；用 /goal status/pause/resume/cancel/next 管理；适合有明确终点的任务；
• 定时任务：自然语言设置提醒，绑定会话、周期性任务 7 天过期需留意续期；我们用它们守住了"每天记录、每周备份、每周回顾"的节奏；
• kimi -p 非交互模式：干完就走，可以嵌进脚本、交给系统定时器，把 Kimi 变成自动化工具链里的零件；退出码可判断执行结果。

到这里，Kimi Code 的核心功能你已经全部拿下了。剩下的四章讲"怎么让它更顺手"（定制配置、写技能、扩展生态）和"换个地方用它"（编辑器、第三方工具、桌面客户端），属于进阶篇，学起来会轻松很多。

定时任务的数据前提

先按第 7 章导出 private-data/records-export.json。定时任务读取该文件并检查导出时间；缺失或过期时报告数据不可用，不声称读取了浏览器实时记录。

10 定制你的Kimi_Code

前面八章，我们用的是"出厂设置"的 Kimi Code——它已经很好用，但还不是"你的"。这一章做三件事：认识配置文件的存放方式、用 AGENTS.md 给项目立下规矩、把你重复使用的流程固化成自己的 Skill。做完这些，Kimi 会越来越像一个了解你习惯的老搭档。

9.1 配置文件与数据都在哪儿

先建立一个全局认知：Kimi Code 的所有本地数据，默认都放在一个目录里——~/.kimi-code/（Windows 原生路线是 C:\Users\你的用户名\.kimi-code\）。里面值得你认识的有三样：

• config.toml：主配置文件，模型的选择、API 来源、各种开关都在这里；
• sessions/：你所有的会话记录（第 5 章讲过，按工作目录分组存放）；
• logs/：运行日志，排查问题时用得上。

日常使用中，最常用的调整是切换模型——在会话里输入 /model，从列表里选择即可，不用手动改配置文件。想改更细的设置（比如默认模型、自定义数据目录），去翻官方文档的 Configuration 章节，这里不展开——本章的重点是下面两个更有"创造感"的定制方式。

9.2 AGENTS.md：给项目立一份"家规"

到目前为止，你每次想让 Kimi 遵守某个约定，都得在对话里说一遍："提交信息用「类型: 简述」格式""代码注释用中文""改完记得跑测试"……说一遍它记一遍，新会话、新同事来了还得再说。

AGENTS.md 就是为解决这个问题而生的：在项目根目录放一个名叫 AGENTS.md 的 Markdown 文件，写下这个项目的约定，Kimi 每次在这个项目里工作时都会自动读到它——相当于给项目立了一份"家规"。

实战：在 weight-tracker 根目录创建 AGENTS.md，把这几条写进去：

# 项目约定

## 技术栈
纯前端三件套（HTML/CSS/JS），不引入框架和第三方库；数据存 localStorage。

## 代码风格
- 变量名用 camelCase，常量用 UPPER_SNAKE_CASE
- 注释用中文
- 每个函数开头用一行注释说明作用

## 工作习惯
- 改动计算逻辑（calc.js）后，必须打开 tests.html 跑一遍测试
- 提交信息遵循「类型: 简述」格式，类型从 feat / fix / refactor / docs / chore 中选

写好后，新开会话让它生效（已有的会话不会自动重新读取）。然后验证一下：随便让它改个小功能，观察它是否主动遵守了这些约定——比如改完 calc.js 后会不会主动提醒"该跑一遍 tests.html 了"。

AGENTS.md 的价值会随着项目变大而凸显：约定写一次，永远生效；团队里每个人、每个 AI 会话都遵循同一套标准。它是"把最佳实践沉淀进项目"的最省事方式。

9.3 自定义 Skill：把重复流程变成一句话

AGENTS.md 管的是"默认规则"，Skill 管的是"可复用的流程"。

想一想这几章里你重复做过的事：生成周报、按固定格式写提交信息、给应用做一遍功能体检……这些事每次都要打一大段提示词。Skill 让你把这段提示词存成一个文件，以后用 /skill:名字 一句话就能调用，甚至 Kimi 会在合适的场景自动想起来用它。

Skill 放在哪儿？ 按作用范围分四级，优先级从高到低：

文件长什么样？ 推荐"目录形式"：建一个以技能名命名的文件夹，里面放主文件 SKILL.md（还可以放脚本、清单等辅助文件）。SKILL.md 由两部分组成——YAML 头部（写元信息）和 Markdown 正文（写给 Kimi 的指令）。

来个实战。我们给体重管理项目做一个"周回顾"技能。在项目根目录创建 .kimi-code/skills/weekly-review/SKILL.md，内容如下：

---
name: weekly-review
description: 根据本周的饮食、运动、体重记录生成一段中文周回顾
whenToUse: 当用户要求生成本周回顾、周报、周总结时
---

请为用户生成一份本周体重管理回顾：

1. 读取应用的数据（localStorage 导出的 JSON，或用户粘贴的数据）
2. 统计：本周体重变化（对比上周末）、日均摄入热量、日均运动消耗
3. 找出：哪几天摄入超标、哪几天坚持得最好
4. 写一段 100~200 字的中文回顾，语气像朋友聊天，先肯定坚持、再温和地指出可以改进的一天
5. 保存为 weekly-review-本周日期.md

保存后新开会话让它生效。以后只要在会话里输入 /skill:weekly-review（或者直接说"帮我做个本周回顾"，它也可能根据 whenToUse 自动调用），它就会按这份流程执行。

再看头部那几个字段的作用：

• name：技能的名字，调用时用 /skill:weekly-review；
• description：一句话说明，Kimi 靠它判断"什么时候该自动想起这个技能"；
• whenToUse：更明确的触发时机描述。

技能还支持参数和占位符（比如 $ARGUMENTS、${KIMI_SKILL_DIR}），可以做更复杂的流程，这些属于进阶用法，用到时查官方文档即可。

体会一下 AGENTS.md 和 Skill 的分工：AGENTS.md 是"永远生效的规矩"，Skill 是"随叫随到的流程"。一个让 Kimi 变得更懂项目，一个让 Kimi 变得更懂你。

本章小结

这一章我们把 Kimi 从"出厂设置"调成了"私人订制"：

• 本地数据集中在 ~/.kimi-code/，日常最常用的调整是 /model 换模型；
• AGENTS.md：项目根目录的一份 Markdown，写下技术栈、代码风格、工作习惯，每次会话自动生效——永远生效的规矩；
• 自定义 Skill：把重复流程写成 SKILL.md，用 /skill:名字 一句话调用，还能被 Kimi 自动触发——随叫随到的流程；我们给项目做了一个"周回顾"技能。

到这里，CLI 的个性化定制你已经掌握了。但 Skill 只是最轻的扩展方式——下一章我们认识四种更"重"的扩展机制：子代理、MCP、Hooks 与插件，把 Kimi 的能力边界再往外推一大圈。

11 扩展生态

上一章我们学会了 Skill——用一份 Markdown 就能给 Kimi 加能力，这是最"轻"的扩展方式。Kimi Code 还有四种更"重"的扩展机制：子代理、MCP、Hooks、插件。新手期可以暂时不用它们，但你早晚会遇到需要它们的场景，这一章先把地图给你，每种都配一个能上手的小实战。

10.1 子代理：让它学会"分身"

到目前为止，一直是一个 Kimi 在和你对话。其实每个会话背后是一个主代理，它还可以把聚焦的子任务派给子代理（sub-agent）去做。

子代理的关键特性是上下文隔离：它只看到主代理写给它的任务描述，看不到你们的对话历史；它干活时的中间过程（搜索、读文件的记录）也不会倒灌回主对话，只有最终结论会回来。这带来两个好处——主会话的上下文保持干净，多个子代理还可以并行工作、互不干扰。

Kimi Code 内置了三种子代理，开箱即用：

多数时候，主代理会根据任务复杂度和子任务的独立性，自己判断什么时候该派子代理。你也可以直接在对话里点名：

先派一个 explore 子代理，摸清这个项目里和数据读写相关的文件，只调查不修改

每次派遣会以审批请求的形式出现（/yolo 模式下自动批准），你能看到它给子代理写的任务描述。

来个实战，体会"分身并行"的感觉：

我要做两件事，派两个子代理并行处理：
1. 用 explore 分析这个项目的数据流：数据从哪进、怎么存、怎么渲染到页面
2. 联网调研 30 种常见食物的热量参考值，整理成清单，为扩充 foods.js 做准备
最后把两份结论汇总给我

它会同时启动两个子代理——一个在本地只读分析代码，一个联网做调研——然后汇总两份报告。如果让主代理串行做，耗时取决于任务长度、启动和汇总开销，不能预设翻倍。

两个提醒：一是每个子代理都独立消耗额度，简单任务没必要分身，主代理自己干更经济；二是子代理继承主代理的权限规则，你批准过的"始终允许"对它们同样生效，不需要重新批准。

本章以 10.2 的一个 MCP 连接为必做；子代理、Hooks 和插件制作是选读。每次只增加一个能力，验证成功后再继续。

MCP 前先运行 node --version、npx --version。没有 Node 时按 Node.js 官方安装说明安装后重开终端。创建 kimi-mcp-lab 目录并放一个 hello.txt，配置中的占位绝对路径必须替换；Windows JSON 路径写作 C:\\Users\\你的用户名\\kimi-mcp-lab。连接后先列工具，再读取 hello.txt，最后在授权范围内创建 probe.txt 并由终端核对内容；连接图标正常不等于工具调用成功。

10.2 MCP：接上外部世界的工具

Kimi 自带的工具（读写文件、跑命令、联网搜索）已经很全，但总有覆盖不到的角落：查公司内部系统的数据、操作某个 SaaS 服务、读一个特殊格式的存储……**MCP（Model Context Protocol，模型上下文协议）**就是为此而生的开放标准——外部进程或服务按这个协议暴露工具，Kimi Code 作为客户端连上去，那些工具就和内置工具一样供它调用。

三种连接方式：stdio（CLI 在本地启动一个子进程，适合本地命令行工具）、HTTP（连接一个已在运行的远程服务）、SSE（旧式协议，新服务优先用 HTTP）。

配置写在哪里：一个 mcp.json 文件，分两级——用户级 ~/.kimi-code/mcp.json（对所有项目生效），项目级 <项目>/.kimi-code/mcp.json（只对当前仓库生效，同名条目覆盖用户级）。也可以在会话里输入 /mcp-config 用交互界面增删改，输入 /mcp 查看各服务器的连接状态。

来配一个最小的例子（官方示例的文件系统服务，需要机器上有 Node 环境的 npx；没有的话读懂原理即可）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ABSOLUTE/PATH/kimi-mcp-lab"]
    }
  }
}

把它写进 ~/.kimi-code/mcp.json，然后新开一个会话（改配置对已经打开的会话不生效），输入 /mcp 就能看到 filesystem 服务已连接。之后 Kimi 就能调用 mcp__filesystem__read_file 这类工具读写已明确创建的 kimi-mcp-lab 练习目录中的文件——注意 MCP 工具的命名规律是 mcp__<服务器名>__<工具名>，审批面板里看到这个名字，你就知道它来自哪个外部服务。

安全上的四条纪律，请务必记住：

• 只连接你信任来源的 MCP 服务；
• 项目级 mcp.json 里的 stdio 服务会在会话启动时执行本地命令——打开含有项目级 MCP 配置的陌生仓库时，Kimi 会弹出信任提示并列出将启动的命令，看清楚再点信任；
• 审批 MCP 工具调用时，留意工具名和参数是否合理；高风险工具（写文件、执行命令）保持手动批准，别用 mcp__* 通配符一次性放行；
• /yolo 模式下 MCP 工具调用会自动批准——只有你完全信任所连接的服务时才敢这么用。

10.3 Hooks：事件驱动的自动触发

第 8 章的定时任务是"到点触发"，Hooks 则是"出事触发"：你预先告诉 CLI"每当某个事件发生，就自动运行这个脚本"，脚本在你的本机执行，里面写什么都行。

典型用途有三类：安全拦截（它执行 shell 命令前，脚本检查有没有危险操作，有就拦下）、完成提醒（后台任务完成时弹个系统通知叫你回来）、自动检查（每次你发消息时，自动往上下文里附加当前 git 分支之类的背景信息）。

配置写在 ~/.kimi-code/config.toml 的 [[hooks]] 数组里，每条规则四个字段：

• event：事件名（必填）；
• matcher：可选的正则，过滤事件目标（比如只匹配某个工具）；
• command：要执行的命令（必填）；
• timeout：超时秒数，可选，默认 30 秒。

常用事件挑几个认识一下：

脚本的返回规则很简单：退出码 0 表示放行，2 表示拦截（拦截原因通过 stderr 传给 Kimi），其他退出码、超时、崩溃都默认放行——这种"出错也放行"的设计叫 fail-open。所以 Hooks 适合做提醒和轻量拦截，不要把它当成唯一的安全屏障，真正的高危操作还是要靠权限审批。

实战一个立刻用得上的：让它改完代码后自动提醒我们跑测试。在 ~/.kimi-code/config.toml 里加：

[[hooks]]
event = "PostToolUse"
matcher = "Write|Edit"
command = "echo '提醒：代码有改动——如果动了 calc.js，请打开 tests.html 跑一遍测试'"

matcher 里的 Write|Edit 是正则，匹配"写入文件"和"编辑文件"两类工具。脚本的 stdout 会附加到上下文里，所以这句提醒 Kimi 自己也看得到——它收到提醒后，很可能主动就把测试跑了。保存配置后新开一个会话生效。

如果想做拦截（比如拦下包含 rm -rf 的命令），思路是：监听 PreToolUse、matcher 设为 Bash，脚本从 stdin 读事件 JSON、检查命令内容，发现危险就 exit 2。完整的示例脚本在官方文档的 Hooks 页面里有，需要时照抄改造即可。

10.4 插件：把能力打包带走

Skill 是一个文件，只能静静躺在你的目录里。如果想把一套工作流分享给别人——团队成员、其他项目的自己——就需要插件：把 Skill、自定义 agent、MCP 服务声明、Hooks 等打包成一个可安装的单元。

先看管理界面。 在会话里输入 /plugins，打开插件管理器，四个标签页用 Tab 切换：Installed（已安装）、Official（官方插件）、Curated（精选第三方）、Custom（从 URL 安装）。也可以用命令直接操作：/plugins install <路径或URL> 安装、/plugins list 查看、/plugins remove <id> 删除。改动插件后，运行 /reload 或 /new 才会生效。

官方插件值得知道，目前有三个，都能在 Official 标签页直接安装：

• Kimi Datasource：用自然语言查询金融行情、宏观经济、企业信息、学术论文、法律法规等专业数据（消耗会员额度）；
• Kimi Browser Extension：让 AI 驱动你自己的浏览器完成网页任务（还需在浏览器里装配套扩展）；
• Kimi Computer Use：让 AI 直接操作你的桌面应用（macOS / Windows）。

再动手打一个自己的插件，把第 9 章做的 weekly-review 技能包装起来。目录结构：

weekly-review-plugin/
├── kimi.plugin.json
└── skills/
    └── weekly-review/
        └── SKILL.md      ← 第 9 章写好的那个文件，复制过来

kimi.plugin.json 的内容：

{
  "name": "weekly-review",
  "version": "1.0.0",
  "description": "体重管理周回顾工作流",
  "skills": "./skills/",
  "interface": {
    "displayName": "Weekly Review",
    "shortDescription": "体重管理周回顾工作流"
  }
}

然后在会话里运行 /plugins install ./weekly-review-plugin（换成你的实际路径），/plugins list 确认安装成功，再 /new 开个新会话，/skill:weekly-review 就能用了——只不过这次它是以"插件提供的技能"的身份出现的。

两个注意事项：本地安装时插件会被复制到 ~/.kimi-code/plugins/managed/，之后修改源目录不生效，要重新安装；插件目前是用户级安装，对所有项目生效。

理清 Skill 和插件的关系：Skill 是内容，插件是包装和分发方式。自己用，写 Skill 就够；要给别人用，就打成插件。

本章小结

这一章我们补齐了 Kimi Code 的扩展版图：

• 子代理：主代理可以把独立子任务派给 coder / explore / plan，上下文隔离、可并行，但每个子代理独立消耗额度；
• MCP：通过 mcp.json（用户级/项目级）接入外部工具服务，工具名形如 mcp__服务__工具；改配置要新开会话，安全四纪律别忘；
• Hooks：在 config.toml 的 [[hooks]] 里配置"事件 → 脚本"，退出码 0 放行、2 拦截、出错默认放行（fail-open）；适合做提醒和轻量拦截；
• 插件：把 Skill 等打包成可安装单元，/plugins 管理，官方有 Datasource、浏览器扩展、Computer Use 三个插件；我们也把 weekly-review 打成了插件。

到这里，"怎么让 Kimi 更顺手"这个话题就讲透了。下一章我们换个"战场"：把 Kimi 装进你的编辑器（VS Code、Zed、JetBrains），以及用 API Key 接入第三方工具。

12 在编辑器和第三方工具中使用

前十章我们围着终端转。这一章换个"战场"：把 Kimi 装进你已经在用的编辑器里，以及用 API Key 接入第三方工具。背后是同一个账号、同一份会员权益，只是交互的地方变了。

先建立一个大局观：不管是 VS Code 扩展、Zed 还是 JetBrains，它们背后跑的核心仍然是 Kimi Code CLI。编辑器只是换了个壳，干活的还是那个你已经很熟的引擎——所以你在 CLI 里养成的习惯、写好的 AGENTS.md 和 Skill，在编辑器里大多依然管用。

11.1 VS Code 扩展：图形化里的 Kimi

如果你平时就在 VS Code 里写代码，这条路最顺。三步走：

1. 打开 VS Code，进入左侧"扩展"面板（快捷键 Cmd+Shift+X / Ctrl+Shift+X），搜索 Kimi Code，点"安装"；
2. 安装后按提示登录你的 Kimi 账号（和第 2 章 CLI 的登录是同一个账号，额度共享）；
3. 用"文件 → 打开文件夹"打开你的项目（比如我们的 weight-tracker），就能在侧边栏里和 Kimi 对话了。

几个新手常遇到的问题，提前说清：

• 提示"没有打开工作区"：这个扩展必须在一个已打开的文件夹里工作，光开一个单独文件不行。解决办法就是打开项目文件夹。
• 提示"找不到 CLI"：扩展底层依赖 CLI。如果你已经按第 2 章装好了 CLI，在 VS Code 设置里把 kimi.executablePath 指向 kimi 的绝对路径即可；还没装的话，先回第 2 章装好。
• 登录失败：检查网络，或者改用 API Key 方式登录（见 11.3），稍后重试。

在 VS Code 里，Kimi 的能力和在终端里基本一致，但体验上有图形化的加成：它改动的代码可以直接在编辑器里看到 diff，文件引用用 @ 一样能唤起。适合"习惯在图形界面里边看代码边协作"的用户。

11.2 接入 Zed / JetBrains：ACP 协议

除了 VS Code，Kimi Code CLI 还支持一种叫 ACP（Agent Client Protocol） 的标准协议，任何支持 ACP 的编辑器都能接入。原理一句话：编辑器把 kimi acp 这个子命令当作一个子进程启动，通过它和 CLI 对话。因为你的 CLI 已经登录过了，所以编辑器里不用再登录一次。

一个共同的坑先排掉：编辑器里配置时，如果 kimi 不在系统 PATH 里，GUI 启动的子进程可能找不到它。最稳妥的办法是用绝对路径——在终端里运行 which kimi（Windows PowerShell 用 Get-Command kimi），把显示的路径抄下来。

接入 Zed：编辑 ~/.config/zed/settings.json，加入：

{
  "agent_servers": {
    "Kimi Code CLI": {
      "type": "custom",
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

command 就是上面查到的路径（如果在 PATH 里可直接写 kimi）。保存后，在 Zed 的 Agent 面板里新建对话，就能选用 Kimi Code 了。

接入 JetBrains 系列（IntelliJ IDEA、PyCharm、WebStorm 等）：通过 AI chat 插件支持 ACP。在 AI chat 面板的菜单里选 Configure ACP agents，加入：

{
  "agent_servers": {
    "Kimi Code CLI": {
      "command": "/Users/你的用户名/.local/bin/kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

JetBrains 对 command 字段要求严格，必须用绝对路径。保存后，Kimi Code 会出现在 AI chat 的 agent 选择列表里。

遇到问题怎么排查：IDE 里提示"agent exited"或"auth required"，先在终端里手动运行 kimi acp——如果它停在那里等待输入，说明 CLI 本身没问题，是 IDE 配置错了（多半是路径）；如果立刻报错退出，按提示处理（最常见的是没登录，回终端 /login 一下再重启 IDE）。

11.3 API Key 接入第三方工具

还有一种更灵活的方式：你已经习惯了某个第三方工具（比如 Claude Code、OpenCode、Codex 等），不想换环境，只想把 Kimi 的模型能力接进去。这时用 API Key。

第 1 步：获取 Key。 到 Kimi Code 控制台（Console）创建 API Key。注意两点：每个账号最多 5 个；Key 只在创建时显示一次，务必立刻复制保存好，丢了只能重新创建。

第 2 步：配置地址。 第三方工具需要两样东西：Base URL 和 API Key。Base URL 按你的工具和所在地区二选一（配置在工具的环境变量或设置里）：

不同工具对地址的要求不同：有的（如 Claude Code）只填 Base URL，工具会自动补全后面的路径；有的（如 Trae）要填完整的请求地址，比如 OpenAI 兼容的完整地址是 https://api.kimi.com/coding/v1/chat/completions。

第 3 步：选模型 ID。 在工具里把模型设成下面四个之一（具体能用哪个取决于你的会员等级，详见官方会员权益说明）：

• k3：旗舰模型，适合大型代码库分析、多文件重构；
• k3-256k：K3 的 256K 上下文版本，日常问答和小改动够用，比 k3（1M）省约一半额度，不支持视频输入；
• kimi-for-coding：K2.8 Preview，最高支持 1M 上下文；
• kimi-for-coding-highspeed：K2.7 Code HighSpeed，输出快，适合追求响应速度的场景。

两个合规提醒：一是配置时保留工具的真实身份标识（User-Agent），篡改它属于违规，可能导致会员权益被暂停；二是再次强调——这里的 API Key 走的是 Kimi Code 会员权益（含额度、有速率限制），和 Kimi 开放平台那个按量计费的 API 是两套体系，别把两套的地址和 Key 混着用。

11.4 四种形态怎么选：一张对照表

学到这里，四种形态你都见过了。把它们放在一起，帮你按场景对号入座：

它们不互斥——同一个账号可以在多台设备、多种形态里同时用。我自己（教程作者视角）的日常是：复杂任务和自动化在 CLI，随手改代码在 VS Code 扩展，两者额度共享、会话各自独立。

本章小结

这一章我们把 Kimi 从终端请进了更多地方：

• VS Code 扩展：扩展面板搜索安装、登录、打开文件夹即可用；记得它必须工作在"已打开文件夹"里；
• Zed / JetBrains：通过 ACP 协议接入，编辑器启动 kimi acp 子进程复用 CLI 的登录态；command 用绝对路径最稳妥，出问题先在终端手动跑 kimi acp 排查；
• API Key：控制台创建（最多 5 个、只显示一次），配合对应的 Base URL 填进第三方工具，模型按会员等级四选一；
• 四种形态同一账号、额度共享，按场景各取所需。

还剩最后一站：给完全不碰终端的用户准备的 Desktop 桌面客户端，以及一份结课清单——我们下章见。

13 Kimi_Code桌面版与结课

前面十一章，我们几乎都在终端里度过。但不是每个人都喜欢对着黑漆漆的窗口敲命令——比如你的家人想用 AI 帮忙整理个表格、写个小程序，让他们先学终端就劝退了。

这一章介绍 Kimi Code Desktop：一个图形化的桌面应用，把 Kimi Code 的能力装进了一个点点鼠标就能用的窗口里。教程用一章的篇幅带你上手，最后以一份"全书结课清单"收尾。

12.1 它是什么，适合谁

Kimi Code Desktop 是一个独立的桌面应用，目前支持 macOS 和 Windows。它和 CLI 的核心能力是同一套：你用自然语言交代任务，它读代码、改文件、跑命令、验证结果——只不过这一切发生在一个图形窗口里，而不是终端里。

它最大的特点是开箱即用、零配置：

• 不用装 Node、不用配环境，下载安装即可；
• 用 Kimi 账号直接登录，不需要手动管理 API Key；
• 界面是图形化的，文件树、对话区、改动对比都看得见摸得着。

所以它的目标用户很清晰：偏好图形应用、不想碰终端的人，或者想在电脑上多一个"打开文件夹就能聊"的轻量入口的人。

12.2 安装与登录

去 Kimi Code 官网下载对应你系统的 Desktop 安装包（macOS 一个 .dmg，Windows 一个 .exe），按常规方式安装：

• macOS：打开 .dmg，把 Kimi Code 拖进"应用程序"文件夹。首次打开如果提示"无法验证开发者"，去"系统设置 → 隐私与安全性"里点"仍要打开"。
• Windows：双击 .exe，按安装向导走完。如果 SmartScreen 弹出提示，点"更多信息 → 仍要运行"。

装完打开应用，按提示用你的 Kimi 账号登录——就是 CLI 那个账号，会员权益和额度是共享的。登录成功后，不需要任何额外配置，直接就能用。

12.3 实战：用 Desktop 打开我们的体重管理项目

光说不练假把式。我们直接用 Desktop 打开做了十一章的 weight-tracker 项目，看看体验如何。

1. 打开项目文件夹：启动 Desktop 后，用它的"打开文件夹"功能，选中我们的 weight-tracker 目录。

2. 看到熟悉的界面：左边是文件树，右边（或中间）是对话区——是不是有点像 VS Code 扩展的感觉？

3. 让它接着干活：在对话框里输入一句你现在已经很熟练的需求，比如：

   看一下这个项目，给我讲讲现在的功能结构；
   然后帮我给首页加一个"最近 7 天体重趋势"的小图表
   

4. 观察它的工作：它会去读项目文件（包括我们写的 AGENTS.md 和 Skill），然后动手改代码。改动会以可视化的 diff 呈现出来——哪行删了、哪行加了，一目了然，比在终端里看更直观。

5. 验收：改完它会让你确认。你打开浏览器刷新 index.html（或者 Desktop 可能内置预览），看看体重趋势图表是不是出来了。

你会发现，虽然换了图形界面，但你在 CLI 里学到的一切都管用：三要素需求描述、验收标准、AGENTS.md 约定、Skill 调用、审查改动……这些"怎么跟 AI 协作"的内功，换个壳依然有效。这就是我们把 CLI 作为主线的原因——内功练好，招式随便换。

12.4 Desktop、CLI、VS Code 扩展，到底怎么选

三种官方形态，给你一句话的选用建议：

它们不互斥，同一账号可以同时装、同时用。一个常见的搭配是：电脑上 CLI 和 Desktop 都装着——复杂的、要自动化的活儿在 CLI 里干；临时想快速看看项目、改个小东西，点开 Desktop 就行。

结课清单：你已经掌握的东西

十二章走完，是时候盘点一下你的收获了。下面这份清单，既是你学会的技能，也是以后可以随时回来翻的" cheatsheet "：

基础认知

• Kimi Code 是一个能干活的 AI 编程 Agent（读、写、跑、规划），不只是代码生成器
• 四种形态：CLI、VS Code 扩展、Desktop、API Key，同一账号额度共享

安装与上手

• 按操作系统装好了 CLI（脚本 / npm / PowerShell），登录用 /login + OAuth
• 认识了 TUI 三要素：对话区、输入框、状态栏

核心操作

• 输入技巧：@ 引用文件、/ 唤起命令、! Shell 模式
• 三种权限模式（默认 / /yolo / /auto）什么时候用哪档
• Plan 模式：复杂任务先审计划再动手
• 过程控制：Esc 打断、Ctrl-S 插话、Ctrl+B 转后台
• 会话管理：kimi --continue 恢复、/sessions、/compact、/fork、/export-md

开发流程（实战项目全练过）

• 需求写法：目标 + 约束 + 验收标准
• 给项目配测试（tests.html），全绿才提交
• 修 bug：症状 + 复现 + 期望，先调查后动手
• 重构有测试和 git 双兜底
• git 习惯：先 init、小步提交、分支隔离、规范提交信息

进阶能力

• 联网搜索 + 图片/视频多模态输入
• /goal 目标模式、定时任务、kimi -p 脚本化
• 定制：AGENTS.md 立规矩、Skill 固化流程
• 扩展生态：子代理并行、MCP 接外部工具、Hooks 事件触发、插件打包分享
• 编辑器接入（VS Code / Zed / JetBrains）、API Key 接第三方

最重要的一句话：工具会更新，界面会变化，但"清晰地表达需求、用验收标准检查结果、让好习惯（测试、git、文档）为你兜底"这套方法，是会跟着你走很久的。

祝你和你的新搭档合作愉快。如果在使用中遇到问题，先去翻官方文档，那里有最权威的答案。

14 进阶学习

用 Kimi Code 做出小工具之后 你可以再往前走一步

第一次让 Kimi Code 做出一个能用的小工具，最让人开心的时刻，往往是点下按钮，发现它真的按自己的想法运行了。

跟着知识库完成体重管理小助手，你已经能记录饮食、运动和体重，也开始学着检查计算结果、修复问题、保存代码版本。接下来，你可能会想：这套方法，能不能用到工作中的项目里？

先把本周统计说明白

给小助手增加“本周统计”，看起来只有一句话，实际却有四个需要提前约定的问题。

比如，你可以选择按自然周统计；漏记的日期不计入平均值，并提示记录不完整；没有记录时显示 “本周暂无数据”；刷新之后保留已有记录。这是一套示例约定，你也可以根据自己的需求调整。

把这些约定写进项目文件，再让 Kimi Code 实现，就有了清楚的验收依据。知识库里的项目规则、测试和会话管理，也能帮助你把依据留下来，方便以后继续开发。

到了真实项目 先理清关联再动手

工作中的项目通常没有小工具这么整齐。给已有系统增加一个模型调用入口，可能同时涉及页面、登录权限、配置、日志和旧接口，可以先按下面的顺序推进。

例如，先让 AI 找到原来的登录和接口处理流程，再约定只改模型入口相关文件，保留已有行为。每完成一小步，都留下测试或实际运行结果。

随着项目变大，有条理地提供背景、控制修改范围、保存验证依据，会成为你与 AI 协作的重要能力。

找一个复杂项目 继续练习

如果你已经完成入门练习，想把 AI 编程带进真实仓库，可以进一步了解《企业级 AI 编程实战营》。

课程以 Claude Code 为主要实践工具，通过规格驱动开发，把需求、任务拆解、实现和验证串起来。 对 Kimi Code 用户来说，可以继续学习其中能够迁移到其他工具的开发方法。

例如，DifyPro 项目会练习理解陌生的大型仓库，再完成小范围修改；OryxOS 项目则把需求、架构、 工具接入和最终验证连接起来。它们提供了比入门小工具更复杂的练习环境。

你可以带着自己的项目来对照课程大纲：目前最难的是理解仓库、控制修改范围，还是验证结果？先找到需要补齐的环节，再决定下一步学什么。

想了解下一步怎么学

如果你希望进一步了解《企业级 AI 编程实战营》的课程内容与学习要求，可以扫描下方二维码，向学习顾问发送「Kimi 项目进阶」，说明自己的基础和想解决的问题，一起判断课程是否适合。