从想法到作品

六章主线与 API 补充教程 · 切换到分章阅读

• 第一章｜先让一个想法动起来
• 第二章｜让 Agent 沿着你的想法做
• 第三章｜为了改好它，我们需要学什么
• 第四章｜改坏了、走偏了，怎样继续
• 第五章｜把好用的方法变成 Skill
• 第六章｜用 MCP 让 Agent 真正操作作品
• 补充教程｜在 DSH 中接入模型，认识 API 配置

---

第一章｜先让一个想法动起来

大家好。我想用一个大家熟悉的小游戏，带大家开始这次 AI 编程的学习：做一条能移动、吃东西、计分的贪吃蛇，再把它逐步改成自己喜欢的样子。

选择它，是因为我们很容易判断结果。蛇有没有移动，撞墙后有没有结束，重新开始是否重置了分数，玩一会儿就能发现。这种能够及时获得反馈的项目，很适合第一次体验“提出想法—得到结果—继续修改”的过程。

这个起点来自 Datawhale 的 Easy-Vibe 教程《AI 时代的编程初体验》。原教程从基础贪吃蛇继续扩展文字、诗歌和图像玩法。我们先做普通版本，再顺着自己的问题学习 Agent 的使用方法。

从一句“帮我做一个游戏”开始

你可以先在脑中想象它的样子：一个方形区域，一条蛇，一颗食物，几个按钮。现在试着告诉另一个人，你希望它怎样工作。你会发现，“贪吃蛇”三个字虽然很熟悉，很多细节其实没有说清：游戏打开后立刻开始，还是等玩家点击？有没有暂停？撞墙结束还是穿过边界？

第一轮先确定最基本的玩法。我们约定：玩家点击开始后，用方向键控制移动；吃到食物会变长并加分；撞到边界或身体则结束；结束后可以重新开始。暂停、难度、主题和排行榜先留到后面。

这就是第一份需求的雏形。它已经可以用来讨论和生成作品。后面如果想增加功能，我们会从这份约定继续修改。

规则 → 游戏

点击开始

撞墙结束

重开清零

0 分等待开始

找到一个能操作项目的 Agent

普通聊天窗口可以给出代码，AI 编程 Agent 还可以借助工具读文件、修改文件、执行命令，有些还能操作浏览器。你可以把 Agent 看成一个能够一边行动、一边读取行动结果，再决定下一步的协作系统。

我们接下来用 ZCode 说明常见操作，已经有 DSH 等环境的同学也可以沿用。先完成三个准备动作：打开应用，接通模型，选择一个项目文件夹。具体安装入口与步骤放在工具准备。

在电脑“文档”中新建 snake-lab，把这次项目集中放在这里。工具选择工作目录时指向它。这个目录会成为 Agent 读取和修改文件的主要位置，你之后找作品、备份和排错也都从这里开始。

第一次接通模型时，可以先发一个普通问题：“请用两句话解释，一个 HTML 文件怎样在浏览器里打开。”收到回答后，再开始创建项目。这样，模型连接与项目实现两个环节就分开了；后面出现问题时，也更容易判断停在哪一步。

配置页里的几个词，先理解到够用

有的工具通过账号登录连接模型，有的允许填写服务地址、密钥和模型名称。它们大致回答三个问题：去哪里请求、用什么凭据访问、希望使用哪个模型。

这里会遇到 API。API 可以先理解为程序使用另一项能力的接口：工具按规定发送信息，模型服务按规定返回结果。你在网页聊天时看见的是对话框，在软件配置里看到的则可能是背后的连接信息。

以 DeepSeek 的官方入门文档为例，base_url 是服务地址，api_key 是访问凭据，model 指定模型。它们应该来自同一个服务的对应配置。官方首次调用说明给出了具体示例。现在先知道这些字段的作用；API 补充教程会带大家在 DSH 里完成配置，再认识这些名词。

如果通过工具里的账号入口连接，就按它的授权步骤完成。连接后看一下可用模型与额度，确认工具能正常回答。密钥自己保管；以后发项目给同学时，把代码与凭据分开。

给出第一份任务

下面这段可以作为首次对话的起点。先读一遍，确认它表达的是你想做的东西：

我想做一个可以在电脑浏览器里玩的贪吃蛇。

第一版规则：
- 点击开始后运行，用方向键控制。
- 吃到食物后蛇变长，分数增加。
- 撞墙或碰到自己的身体后结束。
- 可以重新开始，恢复初始状态。

请先复述你理解的玩法，说明准备创建哪些文件、怎样打开。
先采用简单的单文件 HTML 方案，把需要的样式和逻辑放进去，
方便我找到文件并运行。暂时先不加账号、排行榜或在线接口。
确认需求后，在当前 snake-lab 目录里实现。

这里有几个值得留意的地方。我们给了行为规则，也说清了结果怎样打开；选择单文件，是为了让第一次运行少一些环节；要求先复述，是让双方在修改前有机会发现理解差异。

如果它提出其他方案，你可以问：“这个方案解决了当前哪一个问题？与直接打开 HTML 相比，多了哪些准备步骤？”先听解释，再决定是否采用。现在最重要的是得到一个能试玩的小版本。

看 Agent 做了什么

发送任务后，注意对话中出现的行动：读取了哪个目录，创建了什么文件，是否执行了命令，遇到了什么返回结果。不同工具的呈现方式不同，但都可以沿着“读取—行动—结果”去理解。

例如，它先列出工作目录，发现里面没有文件；接着创建 index.html；然后告诉你打开方式。此时，你可以在文件管理器里找到这个文件。实际文件出现后，才轮到浏览器运行。

如果工具提议执行命令，先看目的和工作目录。命令可能是在启动服务、安装依赖，也可能只是在检查文件。可以直接请它解释：“这一步会做什么，成功后会看到什么？”读懂一条具体操作，比一次认识很多命令更容易。

Agent 的基本循环也就在这里：拿到信息，选择行动，获得结果，再决定继续还是调整。它运行一个检查之后继续修代码，通常也是因为结果提供了新的线索。

先试玩，再判断

打开

试玩

记录

打开并试玩第一版

在资源管理器或 Finder 中找到 index.html，右键选择浏览器打开。页面出现后，先做一轮简单试玩：点击开始、转向、尝试吃到食物、撞墙、重新开始。

先分别观察这些行为，再给出评价：

你做的操作	应该看到的结果
点击开始	蛇开始按固定节奏移动
按方向键	蛇改变移动方向
吃到食物	长度和分数发生变化，出现新的食物
撞墙	当前游戏结束
重新开始	回到初始分数和初始局面，再开始一局

如果某项不符合约定，把现象记下来。例如：“重新开始后分数归零，但蛇长度仍是上一局的长度。”这已经是一条可以继续讨论的问题。

这一轮先把普通流程试一遍。更细的检查会随着新功能逐渐增加，下一章先处理一个更常见的体验问题：游戏虽然能玩，但不是你想要的感觉。

从“它做出来了”走向“这是我的作品”

第一版出来之后，你很可能会产生新想法：移动太快，想增加暂停，按钮位置不顺手，想换成自己喜欢的主题。这就是接下来学习的起点。

我希望大家保留这份最初版本。复制整个项目文件夹，命名为 snake-lab-first；当前继续修改的目录仍是 snake-lab。之后比较两版，你会更容易看到自己的判断怎样改变作品。

也给自己留下三句话：这版已经能做什么，我最想改哪里，为什么想改。先用自然语言写，暂时说不出技术词也没关系。

先想一想

假设你试玩后只写了“体验不好，优化一下”，Agent 可能往哪些方向修改？如果你实际觉得“速度太快，新手还没看清就撞墙”，又应该怎样描述？

想好以后，看看参考思路

参考思路：前一句可能引发配色、布局、动画和逻辑等各种改动；后一句已经指向新手难度。还可以补充希望怎样改变，例如增加一个慢速档，保持其他玩法不变。下一章就从这项修改继续。

---

第二章｜让 Agent 沿着你的想法做

上一章，大家已经得到了一份能玩的贪吃蛇。现在试玩几局，你觉得速度太快，想让第一次玩的人也容易上手。

我想用这一次修改，带大家看清楚一轮轮对话怎样推进。每轮都做一件具体的事：找到现有实现，明确要改什么，讨论方案，动手修改，再根据试玩结果继续调整。上下文、计划模式等词放在章末的 PS 中，大家先跟着对话往下走。

从一句“帮我优化一下”开始

我们很容易这样发消息：

这个游戏太难玩了，帮我优化一下，让它更适合新手。

这句话说出了愿望，但还留着很多选择：难在哪里？是移动太快、转向不灵，还是按钮不好找？“优化”以后，什么表现才算改好了？

我把这种只说希望得到什么、把关键选择都留给 Agent 的表达，叫作“许愿式编程”。它适合刚开始找灵感；已经有了具体问题时，就继续把愿望讲成能执行的修改。

接下来，我们把同一句话一步步改清楚。

把“加个速度”拆成六轮对话

第 1 轮 · 定位

先不要修改代码。请找到贪吃蛇的运行入口、移动速度与开始和重开逻辑分别在哪里，说明每次开局怎样设置速度，并列出相关文件。

先让 AI 建立代码上下文。你需要知道它准备修改哪里，以及判断依据是什么。

第一轮：先让它找到这次要改的地方

先在工具里打开上一章的 snake-lab 项目，再发送：

本次继续修改当前打开的 snake-lab 项目。

请先查看项目，告诉我：
1. 怎样打开和运行这个游戏？
2. 当前控制蛇移动速度的代码在哪里？
3. 开始新一局、重新开始时，速度分别怎样设置？

我觉得当前速度太快，想增加一个慢速档。
这一轮先阅读和说明，暂时不要修改文件。

这轮的目的很明确：先找到当前实现，再谈怎样改。 我们没有要求 Agent 凭“贪吃蛇”三个字重新做一份，而是让它接着已有项目工作。

看回答时，先对照它提到的文件是否真的存在。它指出位置之后，可以在编辑器里打开看一眼；暂时看不懂代码，也先知道这次修改落在哪里。

假如项目中只有 index.html，它可能既是网页入口，也包含移动逻辑；以后文件多起来，入口与速度控制代码可能分别在不同文件中。这里让 Agent 查看实际项目，就能得到这次任务需要的位置。

第二轮：把“慢一点”变成具体玩法

找到位置后，先发一条讨论要求：

我想保留现在的速度，作为“标准”档，再增加一个更慢的“轻松”档。

请先问清会影响实现的选择，比如什么时候切换档位、
重新开始时用哪个档位。先不加入其他功能。

假如它问：“运行中也能切换吗？重新开始要保留档位吗？”我们就把决定说下来：

先按下面的方式做：
- 默认选择轻松档。
- 开始前可以选档位，运行中不切换。
- 每次开始或重新开始，都使用当时选中的档位。
- 重开时，分数和游戏局面重新开始，但保留档位选择。
- 这次先调整速度和相关控件，计分、碰撞规则保持原样。

请把这些规则整理成一份简短修改说明。

这一轮结束，“适合新手”已经变成了一组可以检查的行为。你能判断它是否默认轻松，是否保留标准档，重开是否使用当前选择。暂时没想清楚的细节，也可以先比较两种方案，再作决定。

对比开头的许愿，这里多出来的是你对作品的选择。Agent 可以帮忙提出问题，但最终要做成怎样，由你逐步确定。

第三轮：先看它准备怎样改

接着发送：

请按刚才确认的规则，先列出这次修改的步骤。

说明需要改哪些位置，每一步完成后，我可以怎样运行和检查。
如果某一步会影响计分或碰撞，请单独指出。
这一轮先给方案，暂时不要修改文件。

读这份方案时，对照第二轮的规则：轻松与标准两个档位有没有，默认值有没有，重开有没有。再看是否多出了排行榜、登录或大规模改造。这些都可以在执行前调整。

比如发现它漏掉重开，可以继续发：

方案里补上重开的处理。重点检查旧一局怎样结束，
新一局怎样读取当前档位。其他部分先按这次的范围推进。

这里是在用计划帮助我们看清改动，而不是要求它提前写出每一行代码。需要认识计划模式时，可以看章末 PS 3。

第四轮：先做出一个可以试玩的改动

方案对齐之后，开始执行：

先完成第一步：增加轻松、标准两个档位，并让开始新一局时使用所选档位。

现有速度保留为标准档，轻松档采用更慢的速度。
完成后告诉我两个档位当前怎样设置，以及我该怎样比较。
先停在这一步，等我试玩后再继续处理重开的完整流程。

完成后打开页面，分别选两个档位开始一局，看看区别。这里先把“新一局按档位运行”做出来，得到一次及时反馈。

如果轻松档仍然太快，可以继续说：

轻松档已经比标准慢了，但我试玩时仍觉得开局太急。
请先说明当前两档的速度设置，我想在理解这个设置后再决定改多少。

到这里，已经出现了一个很好的学习入口：为了作出更精确的修改，你开始需要理解“速度怎样设置”。下一章会沿着这个目的展开。

确认这一步的体验后，再发送：

两个档位的首次开局已经可以区分。现在继续处理重开：
结束后切换档位，再重新开始，新一局应使用新的选择。
保留刚才已经做好的档位控件和首次开局行为。

每个步骤都能单独运行和判断，下一步也接着上一步已经做到的结果继续。这就是分步推进的实际用法。

第五轮：用操作和结果反馈问题

假设你试玩后发现：轻松档开始正常，结束后改成标准档，再点重开，速度却仍然很慢。

此时一句“还是不对，再优化一下”，又会把任务交回猜测。把它换成：

我按下面的顺序操作：
1. 选轻松档，开始一局，直到结束。
2. 把选择改成标准档。
3. 点击重新开始。

实际：新一局仍然按轻松档的速度运行。
预期：新一局使用刚选中的标准档。

请先查看相关代码，说明可能原因与依据，再修复这一处。
本轮保持其他玩法不变。

这段反馈给出了复现步骤、实际结果和预期结果。你还不懂内部代码，也已经能提供有效信息。

如果知道某个相关位置，可以补充给它；还不知道时，就让它先查。准确描述自己看到的现象，比先猜一个技术原因更重要。更深入的排错和恢复，我们放到第四章继续讲。

让反馈可以复现

轻松

重开

实际结果待重开

0 格

预期结果待重开

0 格

第六轮：检查这一轮修改，留下下一次的起点

问题处理后，可以发送：

请对照第二轮确认的规则，整理本轮改动：
- 改了哪些文件和位置？
- 我应怎样检查两个档位、重开，以及原有计分和碰撞？

把最终采用的规则和运行方式补到项目记录中。

然后自己按清单试玩，看一下工具的变更视图，保存一个可用版本。重开正确、两档清楚、原有玩法仍正常，这一轮就有了可以留下来的结果。

再记下一项最想继续改的地方。例如：“想增加暂停，但还没确定结束后能否继续。”下一章就带着这项需求往下走。

这六轮对话做了什么

回看开头，你只有一句“让它更适合新手”。现在我们已经有了具体规则、对应代码、一份方案、可以试玩的改动，以及明确反馈问题的方式。

不必每次都完整发送六轮。很小的修改可以合并，没想清楚的地方可以多讨论一轮。重要的是知道当前这条消息要推进什么，以及拿到结果后怎样接下一步。

想练习的话，可以把“慢速档”换成自己的一个需求，先写出最初那句愿望，再写下一轮准备发给 Agent 的话。看看你补充了哪些决定，哪些信息仍需要它帮助调查。

PS｜这几个词分别指什么

PS 1：工作目录与入口文件。 在这个练习中，snake-lab 是项目文件夹，也是选给 Agent 的工作目录；index.html 是浏览器打开游戏的入口。前者回答“这次在哪个项目里工作”，后者回答“从哪里运行作品”。真正需要修改的位置，要按当前实现查找。

PS 2：上下文。 上下文是模型当前实际拿到、能用来处理任务的信息，比如这轮要求、对话内容、已经读取的代码和工具返回结果。选中项目文件夹，表示 Agent 有了定位和读取文件的起点；模型实际收到的文件内容，才属于本轮可用的信息；文件路径只是帮助定位的线索。第一轮让它查看项目，第二轮补充玩法决定，都是在给当前任务补上需要的信息。

从路径，到真正读懂

snake-lab / index.html

待读取

1

2

3

4

增加轻松档

重开保留档位

重开仍是旧速度

路径只是起点

PS 3：先讨论与计划模式。 “先给方案、暂时不改文件”是一条对话要求。有些工具还提供专门的计划模式，可以先在该模式中调查和讨论，再切换到执行。具体模式能做什么，按工具本身的说明理解。

PS 4：分步推进与变更。 一步最好对应一个能运行、能检查的小结果。变更视图里的 diff 展示本次文件差异；第二章先用它了解改动范围，第四章再讲版本与恢复。

需要时回看项目位置、入口与上下文；具体界面操作可以查 ZCode 的文件查看与引用说明。

---

第三章｜为了改好它，我们需要学什么

上一章，我们把“更适合新手”变成了明确的速度档规则。你已经能通过几轮对话推进一次修改。现在再加一个暂停功能，很容易脱口而出：“帮我加个暂停按钮。”

但暂停之后哪些东西停下、哪些东西保留，游戏结束后能否继续，重新开始是否清除暂停状态？如果这些还说不清，Agent 就需要替我们作决定。

我想在这一章带大家练习：为了提出更精确的修改要求，主动学习与这次修改有关的知识，再把学到的东西用回作品。 找代码、请 AI 解释、查文档、作预测，都是为这个目的服务。

这次要学到的，是把“暂停”说准确

先把最初的愿望放在这里：

帮我加一个暂停按钮，点一下停下来，再点一下继续。

如果只看这句话，可能觉得已经很清楚。再往下问两步，就会发现它还没有覆盖完整的行为：

• 游戏还没开始，点暂停会怎样？
• 游戏正在运行，暂停时蛇的位置是否保留？
• 暂停后点重开，是继续旧一局，还是从头开始？
• 游戏已经结束，再点继续能不能恢复？

这些问题决定了功能怎样实现。要回答它们，我们需要认识游戏在不同阶段的情况，以及一次移动怎样被触发。

所以，这一轮学习先围绕两个问题：当前游戏怎样运行；暂停会改变其中哪些关系。 先学到能够作出这些判断，再决定要不要继续深入其他语法和原理。

沿着这次修改，把需要的知识学到能用

下面的几轮对话是一段完整的学习过程。我们始终围绕“把暂停做准确”往前走。

第一轮：先请它指出当前实现

我准备增加暂停功能，但还不清楚当前游戏怎样运行。

请先阅读现有代码，找到：
- 开始一局后，蛇的移动怎样被持续触发？
- 当前怎样记录游戏是否已经开始或结束？
- 重新开始时，哪些数据和运行过程会重置？

标出相关文件与函数，并沿一次“开始—移动—结束”的顺序解释。
这一轮先帮助我理解，暂时不要修改。

拿到回答后，打开它指出的位置，对照着看。先把过程连起来：这里接收开始操作，这里安排移动，这里判断结束，这里负责重新开始。

当前实现可能用定时器，也可能用动画循环。先让 Agent 说明这份项目采用哪种方式。我们需要理解的是眼前这份代码，才能判断暂停应该插入哪里。

如果它一次讲了很多陌生词，可以接着发：

先只解释暂停需要用到的关系。
请用“什么触发移动、什么情况下停止、恢复时需要保留什么”来说明，
并把术语对应到当前代码的位置。

这条补充让解释回到当前目的。你也在决定自己这一轮先学什么。

第二轮：把不同情况摆出来，再作选择

请结合当前实现，帮我区分待开始、运行中、已暂停、已结束四种情况。

分别说明：蛇是否移动、当前位置是否保留、哪些按钮可以使用。
先列出来让我作选择，暂时不实现。

我们可以把希望得到的行为整理成下面这样：

游戏处于什么情况	蛇是否移动	点击暂停或继续	点击重新开始
待开始	否	暂不使用	开始新一局
运行中	是	暂停，保留当前局面	开始新一局
已暂停	否	从当前局面继续	放弃旧局面，开始新一局
已结束	否	暂不使用	开始新一局

这里，我们开始用“状态”描述游戏当前处于哪一种情况。把情况分清，按钮和移动逻辑就有了共同依据。比如“已暂停”和“已结束”都不移动，但前者可以继续，后者需要重开。

你现在已经比“加一个按钮”多理解了一层：暂停功能需要处理不同情况之间的变化。 下一条修改要求，就可以把这些选择写进去。

暂停与继续

位置0

触发器

状态待开始

第三轮：用一个预测检查自己的理解

先别急着让它改。挑一个最容易混淆的情况，试着解释会发生什么：

我的理解是：暂停保留当前蛇、食物、分数和档位；
继续是在这些内容不变的情况下恢复移动。
重开则结束旧一局，重置蛇、食物和分数，再使用当前档位开始。

请结合代码检查我的理解，指出遗漏。
再给我一个需要预测结果的小问题，我先回答。

比如它问：“如果每次继续都新建一个移动循环，却没有处理旧循环，可能出现什么？”你可以先预测，再去看循环怎样开始和停止。

若预测是“可能同时有多个循环，移动节奏异常”，继续确认当前代码是否会出现这个情况。若还无法解释，就把这一点作为新的学习问题，请它单独展开。

我希望大家在这里形成一个习惯：能跟着听懂之后，再试着自己解释或预测。预测与实际不一致的地方，就是下一步值得弄明白的地方。

第四轮：对不确定的细节查一段文档

假设当前代码使用 setInterval 安排移动，你想确认怎样停止它，可以这样问：

当前实现使用 setInterval。我想确认停止旧循环的方式。
请给出对应的官方文档，指出我应该先读哪一段，
再解释它与当前开始、暂停和重开代码的关系。

读到 clearInterval 时，把它与代码中保存的计时器标识联系起来。然后再看：暂停时会停止什么，继续时怎样恢复，重开会不会遗留旧循环。需要时回看计时与暂停的小例子。

如果当前代码采用其他机制，就跟着它查对应文档。需要确认的关系仍然是：谁在触发更新，暂停怎样停止更新，恢复怎样继续。

查文档不是另开一轮漫长学习，而是解决当前解释中一个明确的不确定点。把这一点确认后，就回到修改任务。

第五轮：把理解写回修改要求

现在可以发出比开头更准确的任务：

请按刚才讨论的行为增加暂停与继续：

1. 运行中点击暂停，停止本局的移动更新，保留蛇、食物、分数和档位。
2. 已暂停时点击继续，从保留的局面恢复，避免重复启动移动循环。
3. 待开始和已结束时，暂停/继续按钮不可用于恢复游戏。
4. 重开会结束旧一局的运行过程，重置本局数据，再按当前档位开始。
5. 按钮文字与当前情况一致：运行中显示暂停，暂停后显示继续。

请先说明需要调整的位置，再实施。
保留已有速度选择、计分和碰撞规则。

对比“帮我加一个暂停按钮”，这里多出的条件来自刚才的学习。你理解了要保留哪些内容、何时可以继续，也开始知道重复启动为什么值得检查。

这样，技术知识已经变成了你控制作品的能力。即使具体代码由 Agent 完成，你也能作出更明确的选择。

第六轮：用操作检查要求，也检查理解

改完之后，先按自己作出的选择体验：

请把刚才的暂停要求转成检查步骤。
重点覆盖：运行→暂停→继续、暂停→重开、结束→尝试继续。
同时列出需要顺带检查的已有行为。

随后实际操作，比较结果。例如，暂停后蛇不动，但重开仍显示“继续”，就把这条现象反馈回去；如果重开后移动异常，可以检查旧循环的处理。

每次反馈尽量对应前面的一条要求。你既在验证功能，也在确认自己学到的关系能否解释实际表现。

再看这条“为修改而学习”的路径

这次我们从一个模糊功能出发，依次做了这些事：

指出想改什么 → 找到当前实现 → 理解相关关系 → 作预测、确认疑问 → 写出准确要求 → 运行检查。

“学到什么程度才能继续修改”，也可以放在这条路径里判断：你能否解释当前要改变的行为，能否说明哪些已有行为要保留，能否提出检查方法？如果还不能，就继续补与这个判断有关的一小块知识。

这里的学习有很明确的去向。读完一段解释，马上可以用来改写需求；查完一个接口，马上可以用来判断方案；作出一个预测，马上可以安排检查。

我建议留下三行记录：这次要改什么，学懂了什么关系，怎样用它改变了要求。以后回到项目，也能找回当时作决定的理由。

把同一种方法用到其他任务

这条路径也适用于后面的 Skill、MCP 和 API：

你想作出的修改	为了改准确，需要先弄清什么	学完之后可以提出什么要求
让一个 Skill 在合适任务中触发	工具怎样发现技能，描述怎样表达适用场景	调整描述，并用相关、无关任务比较触发结果
让 Agent 使用一个外部工具	服务提供哪些操作，需要哪些输入	指定工具要完成的任务，并检查返回结果
改善 API 生成的点评	程序传入了什么，怎样取出回答	调整消息与数据，再用固定输入比较效果
改变表格统计规则	每列含义、缺失值与统计范围	写清计算规则，并用小样本核对

先从你想改变的结果反推要学什么，知识就会与自己的任务建立联系。

练习：把一句愿望推进一轮

从“游戏按钮不好用”“生成的点评太空泛”“整理出来的表格不对”中选一个，或者写自己的问题。

先写最初那句愿望，再写下一条准备发给 Agent 的 prompt。说明你要了解哪一部分，学懂之后准备作出什么更精确的决定。

想好以后，看看参考思路

参考思路：“点评太空泛”可以继续问程序传入了哪些本局数据。若只传分数，就先理解输入范围，再决定补数据还是调整要求。学习的结果应体现在下一条任务里。

PS｜阅读时可以回来看

PS 1：状态。 状态描述程序当前处于什么情况。状态变化会影响允许执行的操作和界面呈现。这里用它解释暂停、继续与重开的关系；具体采用哪些变量，取决于当前实现。

PS 2：定时器与循环。 定时器可以按安排重复触发处理，动画循环也可以组织连续更新。先读当前项目采用的机制，再查它对应的启动、停止和恢复方式。

PS 3：代码与文档怎样配合。 代码告诉我们这个项目实际怎样写，文档帮助确认所用接口的规则。让 Agent 解释时，把二者对应到同一次操作，就容易检查是否理解。

现在，暂停的要求已经更清楚了。接下来如果实现后仍有故障，或者一轮修改影响了原有功能，我们就需要第四章的复现、排错和版本恢复。

---

第四章｜改坏了、走偏了，怎样继续

前面我们在贪吃蛇里加入了速度档，并沿着暂停需求完成了学习与修改。现在假设你发现：第一次开始正常，暂停后恢复也正常，但重新开始几次之后，蛇的移动变得异常。

这时候，继续加新功能会让问题更难理解。我们先围绕这一处故障，把信息收集、排查、恢复和交接连起来，学会让项目保持可继续修改的状态。

先把“有时候不对”变成一段操作

你可以从打开页面开始，固定一条最短流程：选择轻松档，开始，暂停，继续，重开三次。记录每一步之后看到的变化。

再分别比较：不经过暂停，重开是否仍异常？只暂停继续，不重开是否正常？标准档是否也出现？这些对比帮助我们缩小条件，而不是让每次尝试都变成另一种情况。

整理后可以发给 Agent：

轻松档首次开始正常。
暂停并继续后仍正常；连续重开三次后移动明显变快。
不操作暂停、直接连续重开，也会出现。
预期每次重开都按当前档位重新启动。
请先调查重开与移动循环的关系，提出有依据的原因和检查方式。

读到这段，Agent 已经知道问题不只与暂停有关。你提供的是观察结果，节省了它重新猜情境的时间。

重复计时 → 越跑越快

正常 · 1 个循环

0 步

重复 · 1 个循环

0 步

运行重开再重开清理

先调查，再决定改哪里

调查可以包括阅读相关函数、搜索循环的创建与停止位置、查看浏览器错误，必要时增加少量诊断输出。请它把发现与假设分开说明：实际代码怎样写，哪种情况可能造成异常，还需要什么验证。

这会让下一步更明确。如果它只说“可能很多原因，建议重写”，可以要求先从当前复现路径检查。一次排查最好能减少未知，而不是不断扩大改动。

你也可以问：“怎样用一个小实验区分这两种解释？”比如检查每次重开是否清理旧计时器，或临时记录一次更新来自哪个循环。实验结束后再移除不需要的诊断内容。

报错和日志该怎样提供

报错通常包含类型、说明、文件位置或调用路径。尽量复制相关完整文本，再附触发步骤。只发最后一个词，可能丢掉最重要的位置线索。

日志则记录程序走到了哪里。某项操作出现了几次、收到什么输入、返回什么结果，都可能帮助判断。先明确想确认什么，再请 Agent 选择记录位置，避免加满整页无用输出。

如果是工具本身连接模型失败，就先处理账号、网络或额度；如果是页面运行后的错误，就提供页面和复现步骤。两类问题属于不同环节，修改方向也不同。

这也是第一章分开确认模型、目录和运行的好处：现在你已经有一张定位问题的地图。

修好目标，再回头看看原有功能

假设原因已经定位，Agent 改好了重开逻辑。先按原来的三次重开复现步骤检查，再试一次速度切换、暂停恢复、撞墙结束和计分。

这些检查各有目的：原步骤确认目标故障消失，其他操作确认这次修改没有破坏相关行为。它们常被称为回归检查。

可以把结果记成一张小表：操作、预期、实际、下一步。第一次做项目时，手动试玩就能产生有效反馈。遇到经常重复的检查，下一章我们再把它整理成 Skill。

如果 Agent 能运行浏览器或测试脚本，也让它提供结果；自己再体验关键操作，尤其是速度、按钮反馈等与感受有关的部分。

怎样保存一个可用版本

一开始复制整个项目文件夹很直观。随着修改增多，可以使用 Git：它记录一组文件在某个时刻的状态，方便比较和恢复。

先掌握几个动作即可：查看当前状态，查看差异，提交一个已经检查过的版本。工具里通常也有图形界面。喜欢用终端时，可以从以下命令认识对应关系：

git status
git diff

status 看哪些文件有变化，diff 看尚未暂存的具体改动。首次建立仓库可以用 git init；准备保存时，选择本次相关文件加入暂存区（也叫索引），再提交。例如单文件项目：

git add index.html
git diff --staged
git commit -m "Add pause and speed selection"

暂存可以理解为选好“这次准备记录哪些变化”。提交信息写清这次做了什么，隔几天再回来也容易认出来。第一次提交若提示缺少姓名和邮箱，按 Git 提示为当前项目设置自己的身份后再继续。

每次保存，都能回看

1. 01初始版
2. 02速度版
3. 03暂停版

初始版已保存

固定速度无暂停

index.html初次保存

恢复时先弄清楚要放弃什么

发现改坏之后，可以先查看差异和历史，找到最近一个可用版本。让 Agent 说明准备恢复哪些文件、会放弃哪些未保存改动，再选择恢复方式。

对于尚未提交、准备放弃的单个文件，git restore index.html 可以还原到索引中的版本；该文件尚未暂存的修改会被覆盖，所以先看差异，想保留的部分先备份。若改动已经提交，则要结合历史选择撤销方式。

刚开始不熟悉时，使用工具的历史和恢复界面也可以。关键是知道自己要回到哪个状态，而不是随机试一串命令。版本记录让你有空间尝试，也让错误更容易收拾。

对话太长时，给项目做一次交接

一轮轮修改后，聊天里可能同时出现旧需求、试过的方案和已经失效的错误。继续让 Agent 从头梳理，会增加负担。

先请它整理一份当前状态：

项目目标：做一个可调整难度的贪吃蛇。
当前能力：基础玩法、速度选择、暂停恢复。
运行方式：浏览器打开 index.html。
当前决定：开局选择档位；重开保留档位并重置本局。
已处理问题：重开后重复移动。
下一步：检查食物生成是否会与蛇身重合。
相关文件与位置：请依据当前代码补充。

把这份说明保存到项目中。新会话先读它，再读需要修改的文件。你也可以使用工具提供的上下文管理功能，保留目标、决定和当前进度，减少无关历史。

这里值得区分：项目文件保留在磁盘里，不代表新会话自动知道此前讨论。交接说明把稳定信息重新送到任务中，相关代码则提供当前事实。

哪些信息值得长期留下

运行方法、常用检查、重要约定和容易误解的地方，可以放在项目说明或工具支持的项目指令文件中。例如 AGENTS.md 等文件，需要按所用工具的规则放置。

我建议先写少量真正影响行动的信息：入口在哪里，怎样运行，当前范围，完成改动后要检查哪些场景。已经能直接从代码看出来的细节，可以让 Agent 按需要读取。

项目约定帮助每次任务从相近的起点开始。完整的检查流程则可以再独立整理，供需要的时候使用。两者的区别，会在下一章变得更清楚。

留下一次可复用的排错经历

用几句话记录：怎样发现问题，最短复现是什么，真正原因是什么，怎样确认修好。下一次遇到类似症状，先查这份记录。

如果几轮之后仍没有缩小问题，就先暂停修改，请 Agent 总结已确认事实、仍在猜测的原因和试过的方法。回到可用版本，或者把故障单独缩成一个小例子，再继续讨论。

这一轮结束，我们得到的除了一个可用游戏，还有一套经常会重复的工作：读取规则、安排试玩、记录现象、整理问题。接下来就把这套方法留下来。

---

第五章｜把好用的方法变成 Skill

前面我们做了几轮检查：先看玩法约定，安排操作，记录现象，修改之后再回归。现在你可能会发现，每次让 Agent 检查作品，都要重新解释这一套。

项目说明能保存目标和约定。如果想把一整套工作方法带到不同任务中，Skill 就很合适。我们先看官方的小例子，再把游戏检查流程整理成自己的版本。

先用一个小例子认识它

Agent Skills 官方入门材料中的掷骰子案例很短：准备一个 SKILL.md，说明什么时候使用、怎样调用随机数命令，然后让 Agent 掷一次骰子。

这个例子容易观察：Agent 是否找到了技能，是否读取说明，是否真的运行相应命令，返回了什么结果。它帮助我们理解 Skill 在工作中的位置。

Skill 可以包含工作步骤、参考资料、脚本和素材。通常先由名称与描述告诉 Agent“有什么能力、什么时候该用”，需要时再读取正文和相关资源。这就是按需读取技能的基本思路。

对使用者来说，先记住两件事：技能要能被工具发现，描述要让 Agent 判断出适用场景。文件放错位置与描述过于含糊，都会影响使用。

从网页检查理解技能的分工

我们前面的实际需要是检查游戏。Anthropic 的 webapp-testing 是一个参考：它把检查本地网页的方法、辅助脚本与使用示例组织在一起。

理解一份检查技能时，可以先问三件事：它处理什么任务，执行时会使用什么能力，需要哪些环境或文件。选择技能时，把这些条件与当前项目对上。

这份技能使用 Python Playwright 脚本与网页交互。下一章使用的 Playwright MCP 则通过工具接口控制浏览器。二者解决问题的入口不同，读到相关名字时可以先记住：Skill 组织方法，具体行动还需要工具和环境来执行。

沿着这个思路，我给大家准备了一份短小的游戏检查技能，文件已经放进资料包，下面直接练习加载与调用。

把当前流程写成一份 Skill

配套文件在 playable-review/SKILL.md。它围绕我们已经讨论过的游戏检查工作组织内容：读取玩法、安排场景、记录现象、排序问题、给出下一步。

最小结构是：

playable-review/
└── SKILL.md

文件顶部放名称和描述，正文写处理方法。例如：

---
name: playable-review
description: 检查可运行小游戏的玩法与交互，按需求安排试玩、记录复现步骤并整理修改建议。适用于游戏初版体验、功能修改后的回归检查和问题整理。
---

name 让我们引用它；description 解释任务匹配关系。名字可以简短，描述要具体到能与其他任务区分。正文再说明怎么做，不要把一整套步骤挤进描述里。

结构和字段可以回看技能说明与例子。先做一个自包含的小文件，等确实出现较长资料或重复脚本，再拆出其他目录。

放进当前工具，让它被发现

在 ZCode 中，可以通过设置中的技能管理入口查看、新建和启停技能。按官方说明添加文件后，刷新列表，先确认名称出现，再引用它处理任务。用户级技能与项目级技能影响的范围不同，当前练习可先限定在自己的项目中。ZCode Skill 文档给出了目录与导入方式。

如果使用 DSH 或其他工具，就按它的技能入口与目录约定添加。同一个技能内容可以理解和迁移，实际发现位置要与客户端匹配。

安装完成后，先明确调用。ZCode 可以在输入框输入 $ 选择技能，再补充当前任务：

$playable-review
请检查当前贪吃蛇的速度选择、暂停和重新开始。
先读玩法约定，列出准备检查的场景，再根据实际操作整理结果。
本轮先给出问题和修改建议。

这次调用中，Skill 提供检查方法，后面的文字提供本次对象和重点。把二者结合起来，才能避免每次都生成同一份空泛清单。

怎样看出它用上了

可以观察技能读取记录，也可以让 Agent 先说明采用了哪套流程，再查看它的实际行动与输出。对于这份例子，输出应能对应到游戏中的场景和现象：怎样操作，预期什么，看到什么，接下来建议改哪里。

只有一份格式漂亮的报告还不够帮助我们继续开发。比如“加强用户体验”很难执行；“暂停后点击重开，按钮仍显示继续”就可以转成明确任务。

如果没有调用，先检查它是否出现在技能列表、是否启用、文件格式是否完整。若明确引用能用而自然任务不触发，再看描述是否写清场景。每次只调整一个相关因素，再用同一条任务试，比较前后变化。

通用指令、快捷命令与 Skill 怎样分工

我们已经有了三种保存信息的方式。可以沿当前项目理解：

需要留下什么	可以放在哪里
项目入口、运行方式、当前玩法约定	项目说明与工具支持的项目指令文件
一句经常发送的任务，例如“总结今天改动”	工具提供的快捷命令或模板
检查小游戏的一套步骤、判断和输出方法	Skill

同一个内容先放到最合适的地方。项目事实经常随版本变，检查方法可以跨版本复用；技能运行时再读取项目事实，就不必把每个版本的细节都写进技能。

例如，轻松档的具体速度属于游戏配置；“检查不同档位下的开局和重开”属于检查方法。分清这两层，技能更容易持续使用。

换个游戏，沿用方法

SKILL.md

1. 01读玩法
2. 02安排试玩
3. 03记录现象
4. 04整理建议

浏览器工具

贪吃蛇01

碰壁结束

开始后移动

怎样把它改成自己的版本

第一次使用之后，找一个真实缺口调整。假设它只检查开始和结束，却漏了暂停恢复，就补上相关场景；若输出问题太多、看不出先后，可以要求按“阻断玩法、影响体验、可选改进”组织，并依据影响说明理由。

修改后用同一份游戏与同一项任务再试，观察是否补上了缺口。每次改动都有使用经历作为依据，技能就会逐渐变得贴合自己。

Agent Skills 的编写建议也强调这一方向：从真实工作或已有材料中提炼，再根据执行结果完善。你前面和 Agent 讨论过的纠正、输入输出和检查步骤，都是很好的起点。

练习：提炼一项重复工作

从自己的学习或社团事务里选一件反复做的事，写清输入、处理方法、输出、适用场景。可以是整理活动通知、检查报名信息，或按固定要求审阅一份材料。

先判断：它是一句快捷提示，还是需要多步骤处理的技能？再写一个有具体适用场景的描述，试着用两条相关任务和一条无关任务检查触发范围。

想好以后，看看参考思路

参考思路：如果“整理活动通知”需要提取时间地点、识别缺失信息、形成统一格式，它适合有一套方法；“把这一句改短”通常直接发任务就可以。

现在我们已经留下了检查方法。下一步很自然：Agent 怎样真正打开游戏，点击按钮，读取日志，把检查做起来？这就轮到工具连接了。

---

第六章｜用 MCP 让 Agent 真正操作作品

上一章我们准备了一份游戏检查 Skill。它已经说明先看什么、怎样检查、如何记录。但执行这些步骤，还需要能够打开网页、点击按钮和读取结果的能力。

如果你使用的 Agent 已有浏览器工具，可以直接用现有工具完成。想再接入一个外部工具时，可以通过 MCP。我们用微软维护的 Playwright MCP作为案例，把“有一套检查方法”接到“能实际操作页面”。

先看一次连接里谁在做什么

想象你对 Agent 说：“打开当前游戏，检查开始和暂停。”其中有几层关系：

你提出任务
    ↓
Agent 决定下一步需要什么操作
    ↓
当前应用通过 MCP 与 Playwright 服务通信
    ↓
服务操作浏览器，返回页面信息和操作结果
    ↓
Agent 根据结果继续检查或报告问题

承载 Agent 的应用通常称为 host，它通过客户端连接 MCP 服务。服务可以提供工具和数据等能力。需要时可以回看浏览器工具与 MCP。

对我们当前的目标来说，先抓住一个重点：模型决定调用什么，具体工具执行动作并返回结果。连上一个服务之后，要继续确认它提供了什么能力，以及 Agent 怎样使用。

为什么先选浏览器案例

浏览器操作的结果比较直观。你能看到页面是否打开、按钮是否点击、界面是否改变；同时还可以检查控制台里的错误。它与前面的试玩直接相连。

Playwright MCP 提供页面导航、结构快照、点击、截图和日志等工具。我们先用这些基本能力，不急着配置一大批服务。等它解决了眼前的检查任务，再根据新的需求扩展。

MCP 也可以连接文档、数据库或其他系统。每次选择服务时，都先说清楚它要补哪一项能力。当前的问题是操作游戏，所以从浏览器开始。

先读配置，再把它填进去

先按工具准备安装 Node.js，运行 node --version，确认版本不低于 18。下面的配置使用 Microsoft Edge；先确认电脑上已经安装 Edge，服务会用它打开页面。

配套文件 playwright.json采用常见的服务配置结构：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "--registry=https://registry.npmmirror.com",
        "-y",
        "@playwright/mcp@latest",
        "--browser",
        "msedge"
      ]
    }
  }
}

先理解它的意思：服务名是 playwright；command 是要运行的程序；args 是交给它的参数。这里由 npx 启动指定的软件包；--registry 指定国内 npm 镜像，首次运行从那里下载；--browser msedge 指定使用已安装的 Edge。

这属于在本机启动的服务，常见通信方式叫 stdio。有些服务运行在远端，需要填 URL，可能还要完成认证。不要把远程地址填进本地命令栏；先看该服务给出的接入方式。

在 ZCode 中添加并确认连接

打开设置中的 MCP 服务管理，添加一个当前项目使用的服务。可以在表单中填名称、启动方式、命令和参数，也可以按完整配置入口导入 JSON。具体入口见 ZCode MCP 文档。

配置完成后启用服务，查看连接状态和可用工具。先找是否出现页面导航、页面快照、点击等浏览器能力。让 Agent 列出这次任务可以使用的浏览器工具，也是一个容易理解的确认方式。

服务显示在线，是连接这一环完成；接下来还要进行一次最小调用，确认它能按预期工作。先让它打开一个普通页面并读取标题，再进入我们的游戏，能把服务问题与项目问题分开。

让工具真的操作一次

Agent MCP

打开页面

读取控件

点击开始

点击暂停

已返回 · 暂停中

127.0.0.1:8000

开始暂停

正在打开

为本地游戏准备一个地址

单文件游戏可以在自己的浏览器里直接打开。交给自动化工具时，我们给它一个本地 HTTP 地址，便于工具访问同一份作品。

在 snake-lab 目录中，通过终端运行：

python3 -m http.server 8000 --bind 127.0.0.1

Windows 上如果使用 Python 启动器，可以改用：

py -m http.server 8000 --bind 127.0.0.1

保持这个终端运行，在浏览器访问 http://127.0.0.1:8000/。目录中有 index.html 时，通常直接展示它。127.0.0.1 指当前电脑，8000 是这个服务监听的端口；命令结束后，这个地址也就暂时不可访问。

终端在这里承担了一个明确任务：把项目文件提供给浏览器读取。你可以让 Agent 帮忙启动，并告诉你它运行在哪个目录、怎样停止。

第一次调用：先观察页面

请使用已连接的浏览器工具打开 http://127.0.0.1:8000/。
先读取页面结构，找出开始、暂停和重开按钮，说明当前可执行哪些操作。

Playwright MCP 主要使用结构化页面信息定位元素。截图适合辅助看外观，按钮操作则应依据页面快照中的元素信息。

如果快照中看不到某个控件，可以先检查页面是否加载、控件是否有明确文字或标签。有些游戏把整个界面都画在画布里，内部元素不会自动变成普通按钮；此时让 Agent 根据实际结构选择检查方式，必要时改善控件表达。

这里又出现了一个按需学习的机会：为了让作品更容易被操作和检查，我们开始关心标签、结构和可访问名称。这些知识有了当前用途，再去学就更具体。

把 Skill 和工具接起来

现在再次调用检查技能：

$playable-review
当前游戏地址是 http://127.0.0.1:8000/。
请使用浏览器工具检查：开始、暂停、继续和重新开始。
记录操作与结果，再指出最值得优先修改的一项。

Skill 提供方法，MCP 工具提供操作能力。它们的组合可以沿一轮具体检查来理解：读取玩法，安排操作，调用工具，记录变化，整理建议。

观察报告是否对应实际行动。涉及蛇身位置、实时移动等画布内部行为时，可以结合截图、日志、代码与人工试玩。把工具能直接观察的结果与还需要进一步检查的部分分清，下一步任务就更明确。

连接失败时，按层找原因

先看错误发生在哪个位置：

卡在哪里	先检查什么
服务启动不了	Node.js、命令和参数、包下载、启动日志
服务在线但没有预期工具	启用状态、工具列表、当前会话是否刷新
工具调用失败	参数、返回错误、浏览器是否启动
页面打不开	本地服务是否运行，端口和目录是否正确
页面打开但检查走不下去	元素结构、按钮状态、实际操作顺序

这样，你可以先处理连接，而不是反复改游戏代码；也可以确认服务正常后，把注意力放回作品。

换一个任务想一想

如果你想让 Agent 阅读外部文档，再修改项目，它需要什么能力？先说清资料在哪里、怎样认证、希望读取什么、输出用在哪里，再去选择合适的服务。

到这里，我们已经走过一条完整路线：把想法说清楚，借助 Agent 做出第一版，学习需要的知识，继续修改；遇到问题就排查和恢复，重复的方法整理成 Skill，需要的工具通过 MCP 接进来。

给自己的项目留一页记录：当前目标、已有结果、下一项最想做的修改，以及准备怎样检查。后面集中实战，我们就从这一步继续。

接下来可以打开补充教程：在 DSH 中接入模型，通过一次界面配置认识 API 的常见名词。

---

补充教程｜在 DSH 中接入模型，认识 API 配置

这一篇，我想带大家做一件简单的事：把自己的模型服务接到 DSH 里，发出一条消息，再从这次操作认识常见的 API 名词。

我们先用界面完成连接。以后在 ZCode 或其他工具里遇到 API Key、Base URL、Model 这些字段，就知道它们各自负责什么。

第一步：准备 DSH 与 API 密钥

从 DeepSeek 官网的 Harness 页面进入桌面端下载。已经安装的同学，直接打开应用。

再打开 DeepSeek API 控制台，登录后找到 API keys 或密钥管理入口，创建自己的密钥。查看当前可用余额或额度，再继续连接。

这里的 API Key 是让软件调用模型的凭据。把它填进工具的密钥栏，自己保管；需要分享配置截图时，把这部分遮住。

第二步：在 DSH 中连接 DeepSeek

打开 DSH 的“设置 → 模型”，找到 DeepSeek 提供商卡片，把刚才创建的 API Key 填进去并保存。

内置提供商会带好对应的服务配置。先用这条最短路径：选提供商，填自己的密钥，保存，再选择模型。设置中已经有默认值的项目，先沿用。

回到会话界面，选择 DeepSeek 下的可用模型，新建一轮对话。可以发送：

请用三句话解释 API，并说明它在我使用的编程 Agent 中做了什么。

收到正常回答后，我们就完成了一次模型调用。保存配置之后要实际发一条消息，才能知道这组配置能否工作。

接着回到自己的项目，发一个很小的任务，例如“请阅读项目说明，概括当前做到了哪一步”。这样就把模型连接接回了前面的协作过程。

第三步：认清最常见的几个字段

如果以后接入其他服务，或者打开自定义提供商表单，通常会遇到这些名称：

常见名称	它回答什么问题	这次可以怎样理解
Provider / 提供商	模型由哪家服务提供？	这里选择 DeepSeek
API Key / 密钥	用哪个账号的凭据调用？	API 控制台创建的密钥
Base URL / 服务地址	请求发到哪里？	DeepSeek 对话接口的基础地址是 https://api.deepseek.com
Model / 模型 ID	具体调用哪个模型？	按可用列表选择；官方示例使用 deepseek-flash
Protocol / API 协议	双方按哪种格式交换信息？	选择提供商文档规定的接口格式

服务地址、协议和模型 ID 要与同一份服务说明对应。通常先选内置提供商最方便；确实需要自定义时，再对照官方 API 配置说明逐项填写。

遇到“兼容格式”这个说法，可以理解为服务采用某种已有接口的请求与返回规则。例如 OpenAI Chat Completions 是一种接口格式名称，选择这种格式仍可以调用兼容它的 DeepSeek 服务。

网页聊天地址与 API 服务地址也分开看：前者供人打开聊天页面，后者供软件发送请求。配置 Base URL 时，使用 API 文档里的地址。

发出一句话，接回一个回答

DSH组织请求

给贪吃蛇加个慢速档

地址凭据模型

先读取当前项目，再添加轻松档。

响应已接收

模型服务等待请求

第四步：看懂一次调用发生了什么

你在 DSH 输入一条消息
        ↓
DSH 按选定模型和服务配置发出请求
        ↓
服务检查凭据、处理请求，返回结果
        ↓
DSH 把回答显示在对话中

这次调用里，DSH 已经替我们处理了请求组织和结果显示。API 就是这条信息交换的接口。以后自己写程序时，也可以完成同样的交换，只是由自己的代码负责发送和读取。

在界面里，先认识请求和响应两个词：Request 是发出去的信息，Response 是服务返回的信息。提示词属于请求的一部分；返回的回答与用量信息属于响应。

第五步：认识费用和能力相关的词

名词	先理解到什么程度
Token	模型处理输入和输出的计量单位之一，不能直接按汉字数换算
Input / Output	发给模型的输入与它生成的输出，可能分别计算用量
Context Window / 上下文窗口	一次处理可容纳的信息规模，与已经学过的上下文有关
Max Tokens / 输出上限	限制生成长度的参数之一，不是精确字数要求
RPM / TPM	每分钟请求数或 token 数等速率限制
Balance / Quota	余额或可用额度，去对应服务的控制台查看
Streaming / 流式输出	结果逐步返回，界面可以逐步显示文字

现在能把字段认出来，知道去哪里找对应值就可以。之后遇到长对话、响应过慢或额度问题，再带着具体问题深入。

连不上时，先按提示检查

现象	先看哪里
保存后仍没有可用模型	提供商是否配置完成，模型是否选中
认证失败或 401	密钥、提供商和服务地址是否对应
余额不足或 402	API 控制台中的余额与额度
参数错误或 400 / 422	协议、模型名称与其他参数
请求过于频繁或 429	调用频率与并发，稍后再试
超时或连接失败	网络、地址及服务状态

具体状态码可以查官方错误说明。如果向同伴或 Agent 求助，带上工具、提供商、模型名、错误文本，以及已经尝试过的办法。

换一个工具，看看能否认出来

在另一款工具中找到模型配置页，试着指出：哪里选提供商，哪里填密钥，哪里是地址与模型名。界面可以不同，我们刚才认识的几种关系仍然可以用来判断。

最后用自己的话回答三个问题：密钥从哪里来？模型请求发到哪里？怎样确认连接完成？如果能说明，并且已经收到一条正常回答，这次接入就走通了。

想继续学自己写程序调用接口，可以打开选读：用 Python 调用模型 API。那里保留了从环境变量到实际请求的完整步骤和配套程序。