Vibe coding on iMBrace - 动手构建

这是课程的第 2 级：动手构建。前面的级别展示一个完整运作的用例；本页则由你亲自动手构建一个。

完成后，你会在自己的测试组织上得到一个能运行的小型退货台：两张数据表、一条任何人都能编辑的退款规则、一个计算步骤，以及一个通过对话接收退货的助手。它刻意做得很小。重点不在这个退货台本身，而在四个习惯——它们让你在 iMBrace 上构建的任何东西都值得信赖，第 3 级“构建得好”会对此深入讲解。下一课让它等待人的决定在这个退货台的基础上继续，并加上第五个习惯：在向客户承诺任何事之前，先由一个人做决定。

你将构建什么

设想一家虚构公司 Harbor Bicycle Co.，在网上销售并维修自行车。你要为它构建退货台。一位客户写信要求退货。这个退货台应当：

把这次请求记录为数据表上的一行，而不是把它留在聊天记录里。
根据 Harbor 任何人都能编辑的规则算出退款金额，而不是靠模型自己做运算。
由一个助手通过对话接收退货：它记录这笔退货，不说出任何退款金额，也不做出任何承诺——因为还没有人做出决定。

退货台刻意停在这里。Decision、Decided by 和 Decided at 保持为空：它们是让它等待人的决定在有人答复一封邮件时填写的记录——绝不是靠在单元格里输入。

这里的一切都不是 Harbor Bicycle Co. 的真实系统——它并不存在。在把这个演示给任何人看之前，请换成你自己的公司、商品和规则。

你需要什么

一个测试组织和一个 API 密钥。如果你还没有，API 密钥指南说明了如何从仪表板生成一个。这里请使用测试组织的密钥——绝不使用生产环境的密钥。
一个通过 MCP 连接到该组织的 AI 编程工具，这样它就能直接看到你的数据表和工作流程，而不用猜测。本页不指定具体工具；任何能保持 MCP 连接并读取文本文件的编程助手都可以。MCP 指南有你所用工具的具体连接步骤——请先完成这一步，再开始下面的第 1 步。如果你的部署未启用 MCP，设置你的编程工具展示了 SDK 的路径。
如果你的工具更倾向于编写真正的 SDK 代码，而不是直接调用平台，请安装你所用语言的 SDK：
Terminal window
```
npm install @imbrace/sdk
```
Terminal window
```
pip install imbrace
```
无论哪种方式，你的工具最终都需要两个环境变量：IMBRACE_API_KEY 和 IMBRACE_ORGANIZATION_ID。把它们保存在本地的 .env 文件中，绝不提交到任何地方；如果可以把变量名交给编程工具，就绝不要把真实密钥粘贴进与它的对话里。
大约一个小时。其中大部分时间用于阅读平台返回给你的内容——这正是本页想要培养的习惯。

本页会用到几个词：数据表（board）是你自己设计的结构化表格——有行，也有带类型的列，就像一张轻量版的 CRM 表。工作流程（workflow，也称为流程）是一连串步骤，一旦触发就会自行运行。原生步骤是平台自带的现成步骤——不用自己编写代码，不用自己托管，也不用自己管理密钥。智能体（AI Agent）是供用户或渠道对话的前端界面；在产品的侧边栏里，它列在“行动模块”（Actions）>“AI智能助手”（AgentIQ）下。

步骤

1. 动手之前先看一看

先别打开编辑器。让你的编程工具告诉你已经有什么。

你输入，大致是：

在我们开始构建任何东西之前：这个组织里已经有哪些数据表？另外，在平台原生工作流程步骤的目录里，搜索与发送邮件和读取邮件相关的内容。

你应该会看到：在一个全新的测试组织中，数据表列表是空的——这是预期结果，不是失败。如果这个组织已经有其他工作在跑，这一步看到的会是其他已有的数据表——这也没问题；等你在第 2 步创建了自己的数据表后，按名称去里面找它就好。不管是哪种情况，你都应该还会看到一份关于邮件的原生步骤简短列表，很可能还夹杂着你没问到的其他渠道。把这份列表读一遍。这是第一个习惯：在考虑自己写一个之前，先找到平台已经提供的步骤。工具从零写出的步骤，需要你持有一个凭证、维护一段代码；原生步骤两样都不需要。这份列表里的邮件步骤，正是让它等待人的决定要用到的那些。

2. 创建保存退货申请的数据表

你输入：

创建一个名为 Return Requests 的数据表，包含以下列：Customer name、Order reference、 Item、Condition、Price、Refund amount、Decision、Decided by、Decided at。

你应该会看到：组织里出现一张新的数据表，带有这九个列，还没有任何行。在平台里打开它，亲眼核对列名和类型——不要只相信工具对自己所做操作的总结。最后三列 Decision、Decided by 和 Decided at，是一个人所给答复的记录：本课里没有任何东西会填写它们，由让它等待人的决定来填写。

如果你的工具说它无法创建任何东西，说明它的 MCP 连接是只读的——这是默认设置。按照 MCP 页面所说的方式添加写入权限（连接地址上的一个标志），并且务必只在测试组织上这样做。

3. 添加两行测试数据

使用虚构数据。即使是在测试组织中，也绝不使用真实的客户或订单信息。

你输入：

在 Return Requests 中添加两行。客户姓名和订单编号请编造得一看就是假的。第一行：一个未拆封的头盔，价格 45。第二行：一把已使用的自行车锁，价格 28。Refund amount、Decision、 Decided by 和 Decided at 留空。

你应该会看到：两行数据，Condition 分别为“unopened”和“used”，Price 已填好，最后四列为空。

Return Requests 数据表已打开，显示字段与两条数据行 1“知识模块”（Knowledge）>“数据表”（DataIQ）。2 Return Requests 数据表的字段与数据行。

4. 把退款规则放在有人能改的地方，而不是写进一句话里

这是第二个习惯，也是本页最重要的一个。在智能体的指令里直接写“未拆封全额退款，已使用退一半”会更快。不要这样做。写进智能体指令里的规则，只有编辑该智能体的人才能修改，不能原样引用给客户看，事后也无法审计。而以一行数据存在的规则，这三点都能做到。

你输入：

创建第二张数据表，名为 Refund Rules，包含两列：Condition 和 Refund percent。添加两行： unopened，100；used，50。

你应该会看到：一张两行两列的数据表。Harbor Bicycle Co. 的任何人都可以打开它，把 50 改成 60，而不用碰工作流程或智能体。

Refund Rules 数据表，任何人都可以编辑的两条规则 1“知识模块”（Knowledge）>“数据表”（DataIQ）。2 Refund Rules 数据表的两条数据行。

5. 构建工作流程，让一个小步骤来做运算

你输入：

在 Return Requests 数据表上构建一个名为 Calculate refund amount 的工作流程，在有行被新增或修改时运行。它应当：读取该行的 Condition，在 Refund Rules 里查找匹配的行，用一个普通的计算步骤把 Price 乘以 Refund percent，并把结果写入 Refund amount。数据表的读取和写入都使用原生步骤。只有乘法运算本身需要你自己写一个步骤，并且保持它纯粹——输入两个数字，返回一个数字，不涉及其他任何事。这个步骤内部不发起网络调用，也不持有任何凭证。

你应该会看到：一个可以在平台自带的编辑器里打开、从头到尾读下来而无需打开任何代码的工作流程。它的大多数步骤都是原生的。恰好有一个步骤是你的工具写的那段简短计算，短到十秒钟就能读完。如果你的工具提供试运行选项，就手动运行一次，检查 Refund amount 是否落在未拆封头盔的 45 和已使用车锁的 14 上。

Calculate refund amount 工作流程：读取数据表、计算步骤与写回数据表，从上到下 1“Find the matching…”查找 Refund Rules 上符合的数据行（原生步骤）。2“Calculate refund (…)”唯一一行手写的计算步骤。3“Write Refund amo…”把结果写回数据行（原生步骤）。

这是第三个习惯：模型擅长判断该适用哪条规则，但不该被信任在压力下、悄无声息地、每一次都算对乘法。让计算步骤去做运算。让模型来做判断，让代码来做计算。

6. 创建智能体

智能体是通过 SDK 的智能体方法（网站上有介绍）或平台的智能体界面来创建的，所以这一步会用到其中一种方式。无论哪种方式，你的工具都可以为智能体编写指令。

你输入：

首先构建一个名为 Log return request 的工作流程，供智能体作为工具调用。它接收 Customer name、Order reference、Item、Condition 和 Price，在 Return Requests 上只用这五个值创建一行，不写入其他任何内容。然后创建一个名为 Return Desk Assistant 的智能体，只给它这一个工具——而不是整张数据表本身。它的职责是：当客户描述想要退的商品时，用这个工具记录下来，并回复对方请求正在审核中。它绝不能说出退款金额，也绝不能做出任何承诺——因为人还没有做出决定。

AI智能助手的智能体列表，Return Desk Assistant 卡片 1“行动模块”（Actions）>“AI智能助手”（AgentIQ）。2 Return Desk Assistant 智能体卡片。

为什么用工具而不是整张数据表：如果把整张数据表都交给智能体，它就能写入其中任何一列，包括 Decision——它可能会批准自己记录的申请。而这个工具只能写入客户提供的那五列，这样决定权就留在了人手里（下一课会构建人如何做决定）。这是第四个习惯：只给智能体一个狭窄的工具，让它做好那一件必须做的事。

还有一点值得写进智能体自身指令：Refund Rules 是按精确值来匹配的，所以要告诉智能体，写入 Condition 时使用规则本身的这两个词——unopened 或 used——绝不能用客户自己的说法，也不能把它翻译一遍。任何一张由自然语言智能体写入、又被工作流程按精确匹配来查找该行的数据表，都需要同样的谨慎。

你应该会看到：对着新的智能体说类似“我想退订单 HB-2044，一顶头盔，还没拆封。我叫 Morgan Ellery，花了 39”这样的话，会在 Return Requests 上产生一行新数据，把这些细节填好，并得到类似“你的退货申请已登记，正由团队审核”的回复——没有数字，没有承诺。几秒钟之后，这一行上的 Refund amount 会自己填好：未拆封的头盔是 39。目前还没有人审核这次申请；让它等待人的决定会加上负责审核的那个人。如果你的工具草拟的指令让智能体自己猜出一个退款数字，这里正好能抓出这个问题：把它退回去，要求把数字从智能体可以说的内容里去掉。然后让它试着自己批准这次申请：它必须做不到，因为它的工具里没有任何东西能写入 Decision。

Return Desk Assistant 的回复：已记录并交由审核，没有金额也没有承诺 1“分析模块”（InsightsIQ）。2 智能体的回复没有提到金额，也没有任何承诺。

如何检查是否成功

不要把编程工具对自己所做操作的总结当作证据。一个听起来合理、构建成功的说法很容易编造出来，也很容易被误当真——自己去看一看。

打开 Return Requests。两行都应显示正确的 Refund amount：45 和 14。两行的 Decision、Decided by 和 Decided at 都是空的。
打开 Calculate refund amount 的运行历史，阅读每次运行的实际状态，而不是它的摘要：每次运行都显示为已完成。
用一个新编的退货案例与 Return Desk Assistant 对话。确认出现了一行数据，几秒钟之后它的 Refund amount 会自己填好，并且智能体的回复不带任何数字，也不带任何承诺。
让这个助手批准一次申请。确认 Decision 仍为空：智能体没有办法写入它。

如果以上任何一条不成立，这比一个看起来没问题、实际上却有问题的构建更有价值。修好出问题的那一处，再检查一遍。

接下来做什么

继续做让它等待人的决定，这是第二次动手。它从这个退货台开始，让退货台在向客户承诺任何事之前，先通过邮件询问一个人。
尝试第二种状况——比如少了包装盒退回的零件——并添加第二条规则行。确认你能改变退款比例，而不用碰工作流程或智能体。
阅读第 3 级“构建得好”，了解这些习惯背后更完整的方法——它讲的是如何让这样的构建经得起交到真实客户手上的考验，而不只是停留在测试组织里。
关于 SDK、CLI 或 MCP 连接本身的任何内容，engineer.imbrace.co 是保持最新的信息来源——本页的内容会先过时，那个网站不会。设置你的编程工具有完整的设置说明。