# iMBrace 构建指南，版本 1.0.3 - 每一页合并在单个文件中


==================== AGENTS.md ====================

# 在 iMBrace 上构建 - 给 AI 编程工具的指示

你正在协助一个人在 iMBrace 上构建——iMBrace 是一个企业级 AI 平台：有供人对话的智能体、存放结构化记录的数据表、把文档读成记录的“文档模块”（DocIQ）、自行运行步骤的工作流程，以及把这一切连接到电子邮件、聊天和网页的渠道。这个文件夹就是方法——如何把设计和构建做好。事实的参考来源是 engineer.imbrace.co。

## 本指南使用的词汇

- **组织（Organisation）**——平台上的一个租户：属于它的数据表、智能体、工作流程和人员。
- **测试组织**——只用来构建和测试的组织，绝不用于真实工作或真实数据。
- **数据表（Board）**——一种由带类型的列和行组成的表格，是平台的结构化记录存放区。
- **工作流程（Workflow，也称为 flow）**——一经触发就会自行运行的一连串步骤。
- **原生步骤**——平台自带的现成工作流程步骤；不用自己编写，也不用自己托管。
- **智能体（Agent）**——供人或渠道对话的前端界面。
- **文档模块（DocIQ）**——平台中把文档读取为数据表记录的部分。
- **文档模型（Document model）**——“文档模块”从某一类文档中提取什么内容，以及这些内容会存到哪里。
- **网关（Gateway）**——SDK、CLI 和 MCP 连接共同对话的地址。
- **MCP**——Model Context Protocol 连接，让你的编程工具能看到这个组织；一旦开通写入权限，还能修改它。

## iMBrace 运行在哪里

一个组织要么位于 iMBrace 的云端，要么位于客户自己的安装——他们自己的服务器，或者私有云。在设计任何东西之前，先问清楚是哪一种。

- 如果是客户自己的安装，请把 SDK 和 MCP 连接指向该安装自己的网关地址，绝不要指向网站示例里的云端地址。
- 由哪些 AI 模型读取数据，是按安装、按组织分别设定的。在放入任何个人数据之前，这个人要先向负责运行该安装的人确认：这个组织所用的每一个模型——无论用于聊天、文档读取，还是搜索——都运行在这个部署内部。在这一点得到确认之前，一律只使用虚构的数据。

## 立场

- **人来决定；你负责辅助。** 提出设计、规则和批准方式的建议；不要代替这个人拿主意。
- **绝不采信任何关于构建的汇报，包括你自己写的。** 要亲自运行它、到平台上核实结果，并展示输出内容。你没有亲眼见过的绿灯，就不是绿灯。
- **如实说明状态。** 你碰过的每一部分，都只会是以下三种状态之一：**proposed（已提议）**——已经设计，还没有构建；**built（已构建）**——已经构建，但还没有在平台上运行并核实；**live（已上线）**——已经运行，并且结果经过人的核实。

## 事实从哪里来

- **SDK、CLI、MCP 和 API 的事实：绝不能凭记忆作答。** 请抓取 https://engineer.imbrace.co/llms.txt，并读取它指向的那一页——是那一页本身，不是它的摘要。这个网站也以 developer.imbrace.co 提供服务；这两个地址是同一个网站。如果连不上，就改读已安装的 SDK 包本身（TypeScript 包里的类型定义、Python 包里的源码）。如果两者都拿不到，就如实说明并提问；绝不能凭猜测写出方法、字段或端点的名字。无论是做规划还是写代码，都要为构建所依赖的每一项 SDK、CLI 或 MCP 事实，指出你会去读的 engineer.imbrace.co 页面。
- **这个组织里现在有什么**——数据表、工作流程、智能体、连接、近期的运行记录：通过 MCP 连接向这个组织查询。动手构建之前，先看一看。
- **该怎么设计：** 就在这个文件夹里。

## MCP 连接

- **在开通写入权限之前，一律只读。** MCP 页面展示了开通新增与更新的参数，以及开通删除的参数。只在测试组织中使用它们。
- **智能体和文件上传要通过 SDK**，或平台自己的界面进行。
- **如果某个安装未启用 MCP**，就改用 SDK 或 CLI 进行。

## 设计新构建时的阅读顺序

1. `build-it-well/use-case-shapes.md`——说出这个问题属于哪一种形状，并用平实的话把各个组成部分画成草图。动手构建之前，先把草图给这个人看。
2. `build-it-well/native-first.md`——在自己编写代码之前，先找出平台自身的步骤或能力。
3. `build-it-well/the-eight-principles.md` 中，适用于你眼前这个决定的那一项原则——不必一次读完全部八项。
4. `build-it-well/human-approval.md`——只要有需要由人决定的地方，就要读。
5. `build-it-well/document-models.md`——只要涉及读取文档，就要读。
6. `build-it-well/anti-patterns.md` 和 `build-it-well/review-checklist.md`——在宣布任何东西完成之前要读。

当这个人正在照着教程（`build-it/vibe-coding-tutorial.md`）做的时候，请改为依次照着它的步骤走；上面这个阅读顺序是给设计新构建用的。第一次接触这个平台：先读 `build-it/set-up-your-coding-tool.md`。该怎么和这个人协作：见 `build-it/working-with-ai.md`。

## 每一次构建都要遵守的规则

1. **不放任何凭证**在工作流程、代码步骤、提示词、webhook 调用，或任何已提交的文件里。凭证只存放在组织自己的连接存储中，或者一个绝不提交的本地 `.env` 文件里。
2. **只使用测试组织的密钥。** 绝不使用生产密钥。
3. **规则和阈值，以人可以编辑的行的形式存在**，而不是写在智能体的指令里。
4. **由模型判断该套用哪条规则；由计算步骤完成运算。**
5. **答案里的每一个数字都带有它的来源**，否则就要在答案里明确说明这个数字不在数据里。
6. **重要的决定，是一行数据上一个被记录下来的值**——谁、决定了什么、什么时候——没有它，下游就什么都不会运行。人在自己本来工作的地方做决定：一封带有“批准”和“拒绝”按钮的邮件，每个按钮打开一个确认页面，只有页面上的“确认”才算数（仅仅打开链接不会决定任何事）——绝不是在数据表里编辑一个单元格。运行在等待时暂停，之后由同一次运行接着完成，并告知提出请求的人。聊天里的一句回复不算批准。智能体绝不能自己写入这个决定：只给智能体范围狭窄的工具，让它只能写入自己该管的部分，绝不能碰整张数据表。
7. **代码步骤是纯粹的**——输入进去、结果出来，没有网络调用、没有密钥——否则就要明确说明为什么不是。绝不要把某台机器的网络地址写进工作流程里。
8. **拒绝回答也是一种数据；被跳过的检查绝不算通过；一个步骤要靠它的结果来验证。** 去检查这个步骤本应写入的那条记录。
9. **个人数据只能留在它所属的那个部署内部。** 不能出现在测试数据、日志、示例，或发往该部署以外服务的提示词中。测试数据一律用虚构的。
10. **可复用的逻辑不带任何客户名称。** 凡是特定于某一家公司的内容，都以配置的形式传入。

## 如何与这个人协作

- 从业务成果出发：谁会用它、现在卡在哪里、它能带来什么。
- 在你提出设计方案之前，先让这个人画出草图；必要时，再带着证据表达不同意见。
- 关于他们构建的每一个论断，都要有依据：一条数据表记录、一次运行的 id、一段粘贴出来的输出。
- 当你错了，就明确说出来，并注明日期。不要悄悄把答案改掉。
- 让仪式感配得上改动的大小。

## 语言

本指南有三种语言版本：英文版在上面列出的路径，繁体中文版放在 `zh-tw/` 下，简体中文版放在 `zh-cn/` 下，两者的每一页都对应着相同的相对路径。当这个人用中文提出需求时，请读取与其用字对应的 `zh-tw/` 或 `zh-cn/` 版本，并用对方所使用的语言作答。以英文版为准：如果译文版和英文版的内容有出入，一律以英文版为准。

## 关于本指南

这是社区版：方法与合作伙伴版的构建指南相同，只是没有附带任何合作伙伴的名称。`VERSION` 说明这是哪个版本；`CHANGELOG.md` 说明有哪些变动。如果某一页误导了你，请告诉这个人——请到 iMBrace 的公开仓库 https://github.com/imbrace-co/api-sdk/issues 开一个议题（issue）。这个版本没有专属的合作伙伴联系人，所以那里是最适合反馈的地方。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== understand/overview.md ====================

---
title: 什么是 iMBrace
description: 什么是 iMBrace、它如何让 AI 保持可靠，以及由什么来管控它——足以向可能合适的客户讲清楚。
level: '0'
track:
- sell
- build
- deploy
verified_on: 2026-09-29
---

# 什么是 iMBrace

iMBrace 是一个企业级 AI 平台。它为企业提供能够根据企业自身审核过的知识回答问题的 AI 智能体、能够读取文档并将其转化为结构化记录的软件，以及能够执行日常业务流程的工作流程。企业可以完全在自己的服务器上运行它，也可以在私有云中运行，或以 SaaS 方式运行。数据存放在哪里、由哪个 AI 模型读取数据，都由企业自己决定。

## 既智能，又精准

iMBrace 让善于理解的 AI 与精确的步骤协同工作，使整个业务流程能够端到端可靠地运行。

- 智能体理解用户的提问，并依据企业自身审核过的知识作答。知识中没有的内容，智能体会如实说明。
- 工作流程精确地完成工作：路由、核对、计算，以及更新其他业务系统，每一次都以同样的方式进行。
- 重要的决定由人来做：工作流程会等待合适的人批准，然后自动继续执行。

两者结合，运行的是真实的业务流程，而不只是对话。

## 为什么需要管控

在企业系统内工作的 AI 智能体需要明确的管控。iMBrace 把这些管控内置在平台之中。

- 访问权限分层管理：按团队划分，让员工只能看到自己所属团队的知识和数据；按角色划分，让每个人的权限与其应管理还是仅使用相匹配；在企业版部署中，还可细分到记录中的单个字段，让同一张表对不同的读者显示不同的详细程度。
- 平台会记录整个系统中的活动——登录、文件上传、渠道变更，以及数据表的变更——每一项都有时间戳，如果是某人操作的，还会记录到本人名下。在企业版部署中，这项记录还会延伸到 AI 智能体的活动。
- 工作流程可以在重要的决策点暂停，等待指定的批准人处理——需要的话可以等上数小时甚至数天。批准人在自己本来工作的地方做决定：一封带有“批准”和“拒绝”按钮的邮件，每个按钮都会打开一个让他们确认的页面。仅仅打开链接，不会决定任何事。一旦他们确认，同一个工作流程就会自动继续，完成未尽的工作。谁做了决定、决定了什么、何时决定，都会随之被记录下来。
- 这些规则由平台自身的检查机制强制执行，而不是靠写进提示词里的任何内容。
- 平台运行在哪里、使用哪个 AI 模型，都由企业自己决定，包括一个从不离开企业自有场所的模型。

## 各部分如何协同运作

客户和员工通过自己已经在用的渠道接入平台：聊天挂件、WhatsApp，或其他已连接的渠道。智能体依托企业审核过的知识作答。需要动手处理的事，由工作流程完成，并按需调用企业的其他业务系统。平台从文档中提取的任何内容，或生成的任何记录，都会落到一张结构化的表上——正是这条记录，让事后核实答案或操作成为可能。一套统一的管控规则贯穿整个闭环。

画面：图解：iMBrace 如何运作，从消息渠道到智能体、工作流程与数据表，统一于一层治理管控之下
*iMBrace 如何运作：消息渠道连接智能体，并以审核过的知识为后盾；工作流程执行工作；结果落于数据表——全都在同一层治理管控之下。*

以上是这个平台的整体概览。[iMBrace 今天能做什么](./capability-truth-table.md) 会逐个领域给出详细说明，并附上页面或界面，方便你亲自查看每一项能力。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== understand/capability-truth-table.md ====================

---
title: iMBrace 今天能做什么
description: 按能力逐项列出 iMBrace 目前能做的事，并附上你可以亲自核实每一项的页面或界面。
level: '0'
track:
- sell
- build
- deploy
verified_on: '2026-09-30'
---

# iMBrace 今天能做什么

下面每一行都是 iMBrace 今天就能用的能力，都对照真实页面或产品本身核实过——不是计划，也不是路线图。凡标注“（企业版部署）”的行，该能力属于这一类部署；其余能力均为通用可用。版本与定价问题请联系你的 iMBrace 联系人。

## 触达客户与员工

| 你可以做什么 | 在哪里查看 |
|---|---|
| 通过 WhatsApp、Facebook Messenger、Instagram、LINE、微信、电子邮件，或你自己网站上的网页聊天挂件与客户交流——所有渠道都汇总在同一个共享收件箱中 | 产品内（“对话”，Conversations） |
| 每一段对话都会被追踪各自的状态——在线、逾期、待客服介入、待处理或已结束——让你的团队始终清楚哪些对话需要回复 | 产品内（“对话”） |
| 按团队拆分对话，可以选择先到先得模式，也可以让团队内所有人自由加入 | 产品内（“团队管理”，Teams；“对话”） |

## 智能体与知识

| 你可以做什么 | 在哪里查看 |
|---|---|
| 构建一个拥有自己的个性、语气和核心任务的 AI 智能体，并为它提供作答所需的参考资料——支持 PDF、Word、纯文本、CSV 或 Excel 文件 | 产品内（“AI智能助手”，AgentIQ） |
| 让智能体直接调用组织中已有的知识，而不必重新上传 | 产品内（“AI智能助手”；“知识模块”，Knowledge） |
| 将某个知识文件夹或数据表限定给指定团队，只有这些团队的成员才能看到其中的内容 | 产品内（“知识模块”） |
| 在较长的多轮往来中保持智能体的上下文：它会记住同一对话中之前的内容 | 产品内（“AI智能助手”；高级设置） |
| 设置一个编排智能体，把任务的一部分交给一个或多个专门的子智能体处理 | 产品内（“创建您的AI智能助手 - 协调者”，Create Your AI - Orchestrator） |
| 在自动化工作流程内部调用智能体或文档提取步骤，让 AI 步骤成为更大流程的一部分，而不是一段独立的对话 | 产品内（工作流程，Workflows；AI 智能体技能） |

## 文档

| 你可以做什么 | 在哪里查看 |
|---|---|
| 把 PDF 或图片——发票、表单、收据、合同、名片等等——转换成结构化记录，使用的是能读懂版面布局的模型，而不是固定模板 | https://engineer.imbrace.co/zh-cn/sdk/document-ai |
| 把提取规则设置一次，保存为“文档模型”，之后同类型的每份文档都能重复使用；版本历史会显示它是如何变化的 | 产品内（“文档模块”，DocIQ；“文档模型”，Document Models） |
| 把提取结果直接发送到数据表，映射到你选择的列，如果需要，还可以同时发送到多张表 | 产品内（“文档模块”） |
| 告诉“文档模块”你的文档使用的语言，以提高提取准确度，手写文档也包括在内 | 产品内（“文档模块”；“设置”，Settings） |
| 把参考资料以多种格式上传到知识文件夹——PDF、Word、PowerPoint、Excel、CSV、视频或图片文件均可 | 产品内（“知识模块”） |
| 限定哪些团队可以使用某个文档模型，方式与限定知识文件夹相同 | 产品内（“文档模块”；“文档模型”） |

## 数据与工作流程

| 你可以做什么 | 在哪里查看 |
|---|---|
| 把结构化记录保存在一张共享数据表上，供每个工作流程、智能体和员工读写 | 产品内（“知识模块”；“数据表”，DataIQ） |
| 通过已连接渠道收到的消息、一个定时计划，或数据表记录的变化——新建、删除，或指定字段被更新——来启动一个工作流程 | 产品内（工作流程；“流程运营模块”，FlowOps） |
| 在工作流程内部通过预先构建好的连接器对接外部系统——iMBrace 原生集成了100多种服务，从 CRM 到电子表格再到工单系统 | 产品内（“应用整合”，Integrations） |
| 把连接器的凭证保存在组织自己的存储中，与工作流程本身分开，这样共享或导出的工作流程定义中都不会带有密钥 | https://engineer.imbrace.co/zh-cn/sdk/workflows |
| 在重要的决策点暂停工作流程，停在原处等待指定的人做决定；对方答复后，同一次运行就会接着往下走，并记录下是谁做了决定、决定了什么、以及何时决定。如果一直没有人答复，这次运行会保持暂停、清晰可见，也不会有任何东西发出去 | 产品内（“流程运营模块”，FlowOps） |
| 在对方本来工作的地方请他们做决定：一封附有事实卡片和两个按钮（“批准”和“拒绝”）的邮件，每个按钮都会打开一个页面，让他们在页面上点击“确认”。打开链接不会决定任何事，而且一旦有一个答案被确认，另一个按钮就会失效 | 产品内（“流程运营模块”，FlowOps，以及发出的邮件卡片） |
| 在答案出来之后把事情做完：批准后，完成的 PDF 和 Excel 文档会通过邮件发给提出请求的人；被拒绝时，会通知这个人，也不会有任何文档发出去。本来就符合规则的请求则无需批准，文档会直接发出 | 产品内（“流程运营模块”，FlowOps，以及提出请求的人的收件箱） |

## 访问与治理

| 你可以做什么 | 在哪里查看 |
|---|---|
| 把知识文件夹或数据表限定给指定团队，让每个人只能看到自己所属的团队 | 产品内（“团队管理”；“访问控制”，Access Control） |
| 按团队内的角色设置成员权限——例如团队管理员与代表的区别 | 产品内（“团队管理”） |
| 把记录中的单个字段限定给特定角色，让同一张表对不同的读者显示不同的详细程度（企业版部署） | 产品内（“访问控制”） |
| 回顾整个平台的活动记录——登录、文件上传、渠道变更，以及数据表的变更——每一项都有时间戳，如果是某人操作的，还会记录到本人名下 | 产品内（“审计记录”，Audit Log） |
| 把活动记录延伸到 AI 智能体的操作（企业版部署） | 产品内（“审计记录”） |
| 访问规则由平台自身的权限检查强制执行，而不是靠写进提示词里的任何内容 | 产品本身 |

## 运行环境

| 你可以做什么 | 在哪里查看 |
|---|---|
| 以托管服务的形式在 iMBrace 自己的云上运行 iMBrace，无需安装任何东西 | https://engineer.imbrace.co/zh-cn/getting-started/setup |
| 把 iMBrace 安装在你自己的基础设施上——单台本地服务器，或私有云部署——而不使用托管服务 | https://engineer.imbrace.co/zh-cn/install/kubernetes |
| 选择由哪个 AI 模型来回答每个智能体的问题——可以用系统默认模型，也可以自行连接和管理提供者，逐个模型设置 | 产品内（“LLM 提供者”，LLM Providers） |

## 基于 iMBrace 开发

| 你可以做什么 | 在哪里查看 |
|---|---|
| 使用官方的 TypeScript 或 Python SDK 针对 iMBrace 进行开发 | https://engineer.imbrace.co/zh-cn/sdk/installation |
| 用一个 URL 和一个密钥，把 AI 编程工具连接到一个正式运行的组织——在你逐项开启写入权限之前，始终是只读的 | https://engineer.imbrace.co/zh-cn/mcp/overview |
| 把平台自身的结构地图交给你的编程工具，让它第一次就能写出正确的代码，而不是去猜方法名 | https://engineer.imbrace.co/llms.txt |
| 从终端管理数据表、智能体、工作流程和文档提取任务 | https://engineer.imbrace.co/zh-cn/cli/overview |

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it/index.md ====================

---
title: 动手构建
description: iMBrace 课程第 2 级——在测试组织上构建一个可运行的小型退货台，然后让它等待人的决定。
level: '2'
track:
- build
---

# 动手构建

课程前面的级别讲解了 iMBrace 是什么，并展示了一个用例从头到尾的运行过程。这一级由你亲自动手构建一个。

## 这一级能让你收获什么

学完之后，你就能用自己已经在用的任意 AI 编程工具，在一个测试组织上构建出一个可运行的小型退货台，并让它等待人的决定。要做到这一点，不需要任何人把源代码交给你——你只需要一个测试组织、一个密钥，以及通过 MCP 连接好的编程工具。

- [设置你的编程工具](set-up-your-coding-tool.md)——测试组织与密钥，以及把你的编程工具连接到该组织。先做这一步。
- [在 iMBrace 上进行 Vibe Coding——动手构建](vibe-coding-tutorial.md)——文字教程。请按顺序跟做；它的设计就是让你在一个真实的测试组织上从头到尾走一遍。
- [让它等待人的决定](make-it-wait-for-a-person.md)——第二次动手：从已经完成的退货台开始，让它通过邮件询问一个人并等待答复，在此之前不向客户承诺任何事。
- [与 AI 编程工具协作](working-with-ai.md)——让你的工具构建出的成果保持可信的立场与护栏。

## 开始之前

- 一个测试组织和一个 API 密钥。绝不能使用生产密钥。
- 任意能够保持 MCP 连接、并能读取文本文件的 AI 编程工具。本教程刻意不指定具体工具——你现在用的是哪一个，它就能配合哪一个。
- 教程大约一小时。“让它等待人的决定”是第二次动手，需要两个你能读取的邮箱地址。

## 完成这一级之后

第 3 级“构建得好”，是这一页所教的这些习惯背后的方法：为什么每一条都重要、缺了它会是什么样子，以及如何在客户发现之前先一步看出差别。第 2 级让你构建出一个能运行的智能体，第 3 级则决定它是否值得交付。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it/set-up-your-coding-tool.md ====================

---
title: 设置你的编程工具
description: 通过 MCP 把 AI 编程工具连接到测试组织，并把 SDK 的地图交给它：测试组织与密钥、MCP 连接，以及确认一切正常的检查。
level: '2'
track:
- build
verified_on: 2026-09-29
---

# 设置你的编程工具

五个步骤，大约十五分钟。完成后，你的 AI 编程工具就能看到测试组织中已有的内容，并针对 SDK
编写代码，而无需凭空猜测。

**方向在这里，事实在那边。** SDK、CLI 和 MCP 的文档位于
[engineer.imbrace.co](https://engineer.imbrace.co/zh-cn)，并按其自身的节奏更新。本页只为每个
步骤指出该读哪一页，不复制任何内容，因为复制来的
参考资料会过时，而过时的参考资料比没有还糟。

*最近一次对照网站核实的日期：2026 年 9 月 23 日。*

## 1. 测试组织与 API 密钥

在测试组织中构建，绝不要在生产环境中构建。把 API 密钥当作组织自己的密码来对待：它拥有其
角色的完整权限。生产密钥绝不能进入编程工具、测试运行或流水线。

测试组织可以建在 iMBrace 的云端，也可以建在你自己的部署环境里——你自己的服务器或私有云中。
负责运维你这套部署的人可以创建一个。

如何在控制台中生成密钥：参见
[API 密钥指南](https://engineer.imbrace.co/zh-cn/guides/api-key/)。

画面：设置的创建外部令牌标签页，含到期字段与创建令牌按钮
*1 “设置”（Settings）>“创建外部令牌”（Generate External Token）标签页。2 “创建令牌”按钮。*

## 2. 安装 SDK 并设置凭证

请按照文档的[设置指南](https://engineer.imbrace.co/zh-cn/getting-started/setup/)操作：它会说明如何安装 SDK、设置凭证，并把客户端指向你的组织。把密钥放进一个绝不提交的 `.env` 文件中，并且只把变量名交给你的编程工具，而不是变量的值：把一个有效密钥粘贴进与编程工具的对话中，这个密钥就不再由你掌控。

## 3. 把你的编程工具连接到组织

平台的网关托管着一个 Model Context Protocol（MCP）服务器，因此没有什么需要安装或运行。你
只需把服务器地址和你的密钥交给工具，它就只能看到该密钥角色所允许的范围，不多不少——而且在
你开通写入权限之前，它只能看到其中的读取部分（见下文）。

针对各工具的具体步骤见
[MCP 页面](https://engineer.imbrace.co/zh-cn/mcp/overview/)。请照着那边操作，而不是照抄
一份副本，因为地址和参数由网站自行更改。如果你更想运行本地服务器，
[CLI](https://engineer.imbrace.co/zh-cn/cli/overview/) 也能做到。

这个连接涵盖的内容：

- **在你开通写入权限之前，它是只读的。** 开箱即用时，你的工具只能查看，不能修改任何内容。
  MCP 页面展示了开通新增与更新的参数，以及开通删除的参数。只在测试组织中使用它们。
- **智能体与文件上传要通过 SDK**或平台自己的界面进行。
- **是否可用取决于你的部署方式与版本。** 负责运维你这套部署的人可以确认它是否已启用。如果没有
  启用，你的工具就通过 SDK 或 CLI 来工作。

连接建好之后，你的工具就同时拥有了两个部分：这份指南回答“应该怎么构建”，而组织本身回答
“这里已经有什么”以及“那个工作流程上一次运行做了什么”。

## 4. 把 SDK 自己的地图交给你的工具

当你的工具针对 SDK 编写代码时，它应该去抓取网站的
[llms.txt](https://engineer.imbrace.co/llms.txt)，并读取它所指向的页面，而不是凭记忆
作答。网站的
[Vibe Coding 指南](https://engineer.imbrace.co/zh-cn/guides/vibe-coding/)
展示了如何在各个工具中把它交接过去。

如果你的机器连不上这个网站——比如处于隔离网络中——你已安装的 SDK 本身就带有每个方法的
说明：TypeScript 包里有类型定义，Python 包里有可读的源码。你的工具可以改读这些。不管是
哪种情况，它都绝不能凭空猜测方法名。

## 5. 验证设置是否成功

让你的工具做两件事，然后自己核实这两件事：

1. “列出这个组织里的所有数据表（board）。”它应当通过 MCP 连接来作答。在一个全新的组织里，空列表
   就是正确答案，不是失败。
2. “调用一次只读的 SDK，列出所有数据表，并把输出结果给我看。”同一份列表应该会通过 SDK
   返回。

如果两者都和你在平台上看到的一致，说明设置已经完成。如果任何一个失败了，那就是凭证或连接
方面的问题；先在这里解决，再动手构建任何东西。

## 接下来

[教程](vibe-coding-tutorial.md) 会用你的工具一步步构建一个能实际运行的小型智能体。
[与 AI 编程工具协作](working-with-ai.md) 讲的是让它构建出的东西保持可信的那套原则。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it/vibe-coding-tutorial.md ====================

---
title: Vibe coding on iMBrace - 动手构建
description: 在测试组织中，使用任意一款 AI 编程工具，构建一个可运行的小型智能体。
level: '2'
track:
- build
verified_on: 2026-09-30
---

# Vibe coding on iMBrace - 动手构建

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

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

## 你将构建什么

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

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

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

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

## 你需要什么

- 一个测试组织和一个 API 密钥。如果你还没有，[API 密钥指南](https://engineer.imbrace.co/zh-cn/guides/api-key/)说明了如何从仪表板生成一个。这里请使用测试组织的密钥——绝不使用生产环境的密钥。
- 一个通过 MCP 连接到该组织的 AI 编程工具，这样它就能直接看到你的数据表和工作流程，而不用猜测。本页不指定具体工具；任何能保持 MCP 连接并读取文本文件的编程助手都可以。[MCP 指南](https://engineer.imbrace.co/zh-cn/mcp/overview/)有你所用工具的具体连接步骤——请先完成这一步，再开始下面的第 1 步。如果你的部署未启用 MCP，[设置你的编程工具](set-up-your-coding-tool.md)展示了 SDK 的路径。
- 如果你的工具更倾向于编写真正的 SDK 代码，而不是直接调用平台，请安装你所用语言的 SDK：

  ```bash
  npm install @imbrace/sdk
  ```

  ```bash
  pip install imbrace
  ```

  无论哪种方式，你的工具最终都需要两个环境变量：`IMBRACE_API_KEY` 和 `IMBRACE_ORGANIZATION_ID`。把它们保存在本地的 `.env` 文件中，绝不提交到任何地方；如果可以把变量名交给编程工具，就绝不要把真实密钥粘贴进与它的对话里。
- 大约一个小时。其中大部分时间用于阅读平台返回给你的内容——这正是本页想要培养的习惯。

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

## 步骤

### 1. 动手之前先看一看

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

**你输入**，大致是：

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

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

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

**你输入**：

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

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

如果你的工具说它无法创建任何东西，说明它的 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。目前还没有人审核这次申请；[让它等待人的决定](make-it-wait-for-a-person.md)会加上负责审核的那个人。如果你的工具草拟的指令让智能体自己猜出一个退款数字，这里正好能抓出这个问题：把它退回去，要求把数字从智能体可以说的内容里去掉。然后让它试着自己批准这次申请：它必须做不到，因为它的工具里没有任何东西能写入 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 仍为空：智能体没有办法写入它。

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

## 接下来做什么

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

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it/make-it-wait-for-a-person.md ====================

---
title: 让它等待人的决定
description: 让退货台通过邮件询问一个人并等待答复，这样同一次运行就会记录这个决定，并通知客户。
level: '2'
track:
- build
verified_on: 2026-10-02
---

# 让它等待人的决定

本课让[教程](vibe-coding-tutorial.md)里的退货台学会等待一个人的决定。新的退货一进来，就会给值班经理发一封带有“批准”（Approve）和“拒绝”（Reject）两个按钮的邮件；在对方答复之前，不会向客户承诺任何事。对方一答复，同一次工作流程运行就接着往下走：把决定、审核人的姓名和时间写在这一行上，然后通知客户。

这是第二次动手。请从已经完成的退货台开始；你在教程里构建的任何东西都不会被丢掉。

## 你将构建什么

一个在任何东西送到客户面前之前，先等一个人答复的退货流程。你要在自己的收件箱里，扮演审核人——Harbor Bicycle Co. 的值班经理 Jordan Vance。

1. 一笔新的退货出现在数据表上，退款金额照旧算出来。
2. 退货台给审核人发一封邮件，写明这笔退货的事实，并带有两个按钮：“批准”（Approve）和“拒绝”（Reject），然后暂停。等待期间，不会有任何东西发给客户。
3. 每个按钮都会打开一个显示所选结果的页面。仅仅打开它，不会决定任何事；只有页面上的“确认”（Confirm）按钮才会做出决定。
4. 审核人确认之后，同一次运行接着往下走：在这一行上写入 Decision、Decided by 和 Decided at，然后给客户发邮件——批准就写明退款金额，拒绝则是一段不带金额的简短致歉。

做决定时，没有人需要在单元格里输入任何内容。这里的一切都不是 Harbor Bicycle Co. 的真实系统——在把它演示给任何人看之前，请换成你自己的公司、审核人和措辞。

## 你需要什么

- 你在[教程](vibe-coding-tutorial.md)里完成的退货台，在同一个测试组织上：Return Requests 和 Refund Rules 两张数据表、Calculate refund amount 工作流程（新的一行会自己得到 Refund amount），以及 Return Desk Assistant。
- 同一个 AI 编程工具，像教程里那样，通过 MCP 以写入权限连接到该组织。
- 两个你能读取的邮箱地址：一个扮演审核人，一个扮演客户。两个指向同一个收件箱的地址也可以，比如你邮箱账户的一个别名。只使用你自己的地址——绝不使用真实客户的地址，也不使用同事的地址。
- 组织里一个名为 Gmail 的邮件连接，或者一个能登录来创建它的人。第 1 步会指出去哪里看。

本页会用到几个词：**运行**（run）是工作流程的一次执行；处于**暂停**（paused）状态的运行，是在它的等待步骤处停了下来，等有人答复之后，再从原处接着往下走。**审核人**（reviewer）是收到邮件的那个人；Decided by 记录的是他的姓名。**一次性链接**（one-time link）是只对一次答复有效的地址，末尾带一段随机代码；退货台只保存这段代码的**指纹**（fingerprint）——一种单向的“打乱”，能用来核对一段代码，却永远还原不出它。答复之后，这个链接会显示这笔退货已经做出决定。**确认页面**（confirm page）是邮件里的按钮所打开的页面：它显示所选的结果，只有页面上的“确认”按钮才会记录它。**批准任务**（approval task）是运行创建并等待的那一项，它有两个答案，“批准”和“拒绝”；答复的人并不需要看到它。**决定链接**（decision link）是批准任务自己为某一个答案准备的链接：一旦打开就立刻决定，所以它只放在一张私有数据表里（第 2 步会构建它），绝不放进邮件。**代码步骤**（code step）是你的工具写的小步骤，与之相对的是平台自带的原生步骤。

## 步骤

在下面的提示词里，方括号标出的是由你的工具填入的值。其中只有两处要由你来提供：你能读取的那两个邮箱地址——第 3 步里审核人的地址，第 4 步和第 5 步里客户的地址。

### 1. 先把退货台准备好

先做两件小事：给客户的地址留一个位置，再把邮件连接准备好。

**你输入**：

> 在 Return Requests 中添加一个 Customer email 列（纯文本）。所有行保持原样。

给客户的确认邮件会发到这一行上的地址，所以退货台需要这一列。邮件本身通过平台自己的连接发出，绝不通过工作流程里的任何东西。打开“行动模块”（Actions）>“流程运营模块”（FlowOps）>“更多”>“连接”：邮件凭证就在那里，是一个独立命名的连接，名为 Gmail。如果没有，就需要有人在每个组织里登录一次 Gmail 来创建它——请在第 3 步之前做好。使用“连接”列表里用于新建连接的按钮，并用你能读取的 Google 账号登录；退货台的邮件会从这个账号发出。

画面：流程运营模块的“连接”列表，显示一个名为 Gmail 的连接
*1“流程运营模块”（FlowOps）>“更多”>“连接”。2 唯一一个名为 Gmail 的连接。*

本课是按 Gmail 连接来编写和检查的。如果你用的是别种邮件连接，请在粘贴之前，把第 3 步第 9 点里的 Gmail 一词换成它的名称，并在信任这次运行之前，先确认两封邮件都能送达。

这是教程的第一个习惯——使用平台自带的东西——一路延续下来：凭证属于平台自身的连接库，绝不属于某个工作流程。如果之后导出一个工作流程，打开导出的文件，确认里面没有任何密钥或密码。

**你现在应该会看到**：Return Requests 有十列，Customer email 是最后一列，每一行里都是空的；还有一个“连接”列表，里面有一个名为 Gmail 的连接。

### 2. 构建确认决定的页面

在能请任何人做决定之前，先决定他们在哪里答复。审核人会从一封带有两个按钮的邮件里做决定，每个按钮都会在 iMBrace 上打开一个页面，显示所选的结果，并请他们确认。这一步构建的是那个页面，以及它所核对的、存放一次性链接的私有数据表。发送邮件的工作流程由第 3 步构建。

请先读提示词下面的通俗说明，再粘贴整个提示词。它是写给你的工具的，所以你不必看懂其中的每一个技术词。

**你粘贴**，放在一条消息里：

> 分两部分，构建一个用来确认决定的地方。
>
> 第一部分：一张名为 Return Decision Links 的私有数据表，包含以下纯文本列：Fingerprint、Group、Action、Order reference、Decision link、Expires at、Used at、Used action、Created at。不要 Link-type 列。Decision link 列存放承载批准任务决定的那个链接，这个批准任务由下一步创建。只有工作流程使用这张数据表；不要把它交给任何智能体。
>
> 第二部分：一个名为 Confirm a return decision 的工作流程，以公开页面作答——不用登录，不用密钥。使用能直接回应调用方的触发器，并以原始 HTML 回复（content type 为 text/html）。页面地址带一个名为 t 的随机代码。它的工作方式如下：
>
> 1. 从 t 中取出代码（有人访问地址时，从地址里取；按下页面自己的按钮时，从名为 t 的表单字段里取）。算出它的单向指纹。只比较指纹；绝不保存或显示代码本身。
> 2. 在 Return Decision Links 里找到带有这个指纹的行。没有代码，或者没有这一行：显示一个简单页面，写着“This link is not valid.”，没有按钮。
> 3. 如果有这一行，就读取与它共用同一个 Group 的每一行，并按 Order reference 读取 Return Requests 上的这笔退货。链接有三种状态：fresh（未使用、未过期）、used（Used at 已填）或 expired（已过 Expires at）。
> 4. 访问只显示页面，不改变任何东西。Fresh：显示“Approve return [order reference]?”（或“Reject return [order reference]?”）、客户、商品和退款金额、一个把代码回传的 Confirm 按钮，以及这一行文字：“Nothing is decided until you press Confirm.”；Used：显示“This return has already been decided.”；Expired：显示“This link has expired.”
> 5. 只有在 fresh 的链接上按下 Confirm 时：先使用 Decision link 里的链接（一次不带凭证的普通 GET；即使失败也继续往下走，这样你能读到它的状态）。如果状态是 200 到 299，就把这个 Group 的两行都标为已使用（Used at 为当前时间，Used action 为该动作），并显示“Return [order reference] approved”（或“rejected”），外加一行说明客户正在收到邮件。如果失败，什么都不改，保持链接仍可使用，并显示“Your decision was not recorded. Try the button again in a minute.”
>
> 每条路径都以一个页面结束。用一个只把值变成文本、并对插入的每个值做转义的小型代码步骤来生成页面：不发起网络调用，不持有凭证。数据表的读写、调用和响应使用原生步骤。发布之后，把页面地址告诉我。

**通俗地说。** 私有数据表排在最前面。每一行保存一个按钮的一次性链接——以指纹保存，绝不保存代码本身——以及那个按钮的决定链接，由第 3 步填入。Group 把一笔退货的两个按钮关联在一起。只有工作流程使用这张数据表，所以不会有任何智能体拿到它。然后是页面，逐点说明：

1. 页面从链接里读出代码，只保留它的指纹，所以代码本身不会被存在任何地方。
2. 对不上任何一行的链接，会得到一个显示“not valid”的简单页面，没有按钮。
3. 一个真实的链接，会根据私有数据表判定是 fresh、used 还是 expired；页面上显示的事实，则来自这笔退货自己的那一行。
4. 访问只显示事实和一个“确认”按钮。邮件扫描程序和预览功能会打开它们发现的每一个链接，所以打开一个链接不能决定任何事。
5. 只有“确认”会做出决定。页面先记录答复，再让两个按钮一起失效，所以一笔退货只会被决定一次；如果记录失败，什么都不会改变，页面会如实说明。

大部分步骤都是原生的。其余是小型代码步骤，它们只对拿到的值做计算；没有一个发起网络调用或持有凭证。

**你现在应该会看到**：在“知识模块”（Knowledge）>“数据表”（DataIQ）里，有一张新的数据表 Return Decision Links，有九列，没有行。在“行动模块”（Actions）>“流程运营模块”（FlowOps）里，有一个已发布的工作流程 Confirm a return decision；打开这个工作流程，就能进入它的运行历史。让你的工具告诉你页面的地址，在无痕窗口里打开它：先是地址后面什么都不加，再是加上 `?t=` 且后面什么都没有，再是加上 `?t=notacode`。每一次你都会看到同一个简单页面，上面写着“This link is not valid.”，没有按钮。在运行历史里，每次访问都显示为一次已完成的运行，没有任何数据表被改动。

画面：不带链接打开的确认页面：一句简单的话，没有按钮
*不带链接打开的页面：一句简单的话，没有按钮。*

这个简单页面是正确的第一个答案：没有链接，就没有什么可决定的，也没有按钮可按。你会在第 4 步里看到带着真实链接的页面。

如果你看到的不是这一句话，就把你看到的原样告诉你的工具，并要求它让这个工作流程以一个无需登录的网页来作答，然后在继续之前，再把地址打开一次。

页面背后的规则：邮件里的链接不是一项决定。打开链接只会显示一个页面；只有“确认”才会做出决定。随机代码从不被保存，保存的只有它的指纹，而存放指纹的数据表是私有的。[人工批准](../build-it-well/human-approval.md)说明了原因。

### 3. 通过邮件询问，等待答复，然后通知客户

这一步是退货台开始等待的地方。一个工作流程通过邮件询问一个人，在等待步骤处停下，只有在对方确认之后，同一次运行才会把决定写到这一行上，并通知客户。请把整个提示词放在一条消息里交给你的工具——询问的一半和收尾的一半是一体的——并且在它说这个工作流程已发布之前，不要添加任何退货。你在这里要提供的一个值，是审核人的地址。和第 2 步一样，请先读提示词下面的通俗说明：提示词是写给你的工具的。

**你粘贴**，放在一条消息里：

> 构建一个名为 Apply return decision 的工作流程：它通过邮件请一个人做决定，等待答复，然后把事情做完。它在 Return Requests 某一行的 Refund amount 被写入时启动——是针对 Refund amount 的“列已更新”（column updated）自动化，不是“行已创建”（row created）。审核人是 Jordan Vance，地址是 [你自己的地址]。按顺序做这些：
>
> 1. 读取这一行。除非 Order reference 和 Refund amount 都已填写、且 Decision 为空，否则什么都不做。
> 2. 读取 Return Decision Links 中属于这个 Order reference 的行，按 Created at 从新到旧，取一行。如果读到一行且它的 Used at 为空，或者读取失败，就说明已经在请某个人决定：到此停止。不要第二个任务，不要第二封邮件。
> 3. 用平台自带的日期步骤获取当前时间（UTC）。
> 4. 一个小型代码步骤把这一行变成决定卡片：标题“Return [order reference] needs a decision”、一句话的概要，以及一张包含 Customer、Order reference、Item、Condition、Price 和 Refund amount 的表格。卡片上不写截止决定的时间。
> 5. 用平台自带的任务步骤创建一个批准任务：以那张卡片作为它的描述，带两个选项，Approve（绿色）和 Reject（红色）。把它分配给我的 API 密钥所代表的用户。绝不要让被分配人为空，也绝不要分配给同事。
> 6. 一个小型代码步骤生成两个随机代码，Approve 一个、Reject 一个，并为每个代码算出单向指纹——与确认页面用的是同一种方法。每个一次性链接是 Confirm a return decision 页面的地址，加上 ?t= 和它的代码，有效期七天。批准任务对每个答案还有它自己的决定链接，也就是携带决定的那个链接：只在这一点里读取它们，别处一概不读，并且绝不要把它们放进邮件、页面、Return Requests 的某一行或回复里。
> 7. 用原生数据表步骤向 Return Decision Links 写入两行，每个按钮一行：指纹、Group（任务的 id，两行相同）、Action、Order reference、Decision link（批准任务对应那个答案的决定链接，纯文本）、Expires at 和 Created at。Used at 和 Used action 保持为空。绝不保存代码。
> 8. 一个小型代码步骤把同一张卡片渲染成带两个按钮的 HTML 邮件，Approve（绿色）和 Reject（红色），每个按钮只指向第 6 点中它自己的一次性链接，绝不指向决定链接，另加一行文字：“Each button opens a page where you confirm. Nothing is decided by opening a link.”
> 9. 用平台自带的 Gmail 发送邮件步骤（Send Email）发出，通过组织的 Gmail 连接，使用该组织提供的这个步骤的最新版本。如果还没有邮件连接，就停下来告诉我：需要有人登录来创建它。发件人名称为“Harbor Bicycle Returns Desk”，其中不带逗号。主题为“Return [order reference] needs your decision”。
> 10. 等待批准任务（也就是会等待答复的那个任务步骤）。第 5 到第 10 点必须一个接一个地连续运行：中间没有任何东西，并且在第 10 点之前的任何地方，都不能有会暂停或休眠的东西。
>
> 答复回来、运行接着往下走之后：
>
> 11. 再按 Order reference 读取这笔退货。
> 12. 对答复采取行动。只有当 Decision 仍然为空、并且你刚读到的这一行就是启动这次运行的那一行时，Approve 或 Reject 才算数；其他任何情况都不写入任何东西。Approve：获取时间（UTC）；在这一行上写入 Decision 为“Approved”、Decided by 为“Jordan Vance (confirmed by email)”，以及 Decided at；然后才给 Customer email 里的客户地址发邮件，主题为“Your Harbor Bicycle return is approved”，纯文本，写明退款金额。Reject：同样的做法，Decision 为“Rejected”，主题为“Your Harbor Bicycle return was not approved”，内容是一段不提任何退款金额的简短致歉，并说明请联系退货台。
>
> 每一次数据表读写、任务、等待、时钟和邮件，都使用原生步骤。只有第 4、6、8 点使用小型代码步骤。

**通俗地说**，逐点来看。询问的一半：

1. 除非这笔退货已经就绪，否则什么都不做：它有订单编号和退款，而且还没有人决定过它。
2. 一次只问一个人：如果这笔退货已经在等答复，就停下，这样对这一行的第二次写入不会引发第二次询问。
3. 读取时钟，好让链接有一个过期时间。
4. 把审核人需要的事实放在一张卡片上。
5. 创建运行要等待的批准任务：一个带两个答案“批准”和“拒绝”的项目，归属于你的 API 密钥所代表的用户。
6. 生成两个一次性链接，每个按钮一个，并取出批准任务自己的决定链接。只有这一点会从批准任务里取它们；此后它们只存在于私有数据表里，只有确认页面会用到它们。
7. 把每个按钮的指纹和它的决定链接保存在私有数据表里，确认页面会在那里找到它们。
8. 把卡片变成带两个按钮的邮件。
9. 通过组织的 Gmail 连接把它发给审核人。
10. 等待。运行在这里暂停，停在原处，直到审核人答复。

收尾的一半，答复之后：

11. 再读一遍这笔退货，这样运行就是基于这一行现在的样子在工作。
12. 先写入 Decision、Decided by 和 Decided at，再给客户发邮件。同一行只有第一个答复才算数；其他任何情况都不写入任何东西。

第 4、6、8 点是小型代码步骤，和教程里的计算属于同一类：每一个都只对拿到的值做计算，不发起网络调用，也不持有凭证。

**你现在应该会看到**：在“行动模块”（Actions）>“流程运营模块”（FlowOps）里，Apply return decision 已发布，Calculate refund amount 保持不变。打开 Apply return decision，从上往下读：创建批准任务的步骤、通过 Gmail 发送邮件的步骤和等待的步骤依次排列，在等待之前没有任何会暂停的东西。要检查，可以让你的工具按顺序列出 Apply return decision 的步骤，只要名称，再拿这份清单和画布对照。也让它确认，这里做出的指纹和 Confirm a return decision 里的指纹用的是同一种方法。现在先不要添加退货；第 4 步会来做。

如果你的工具提问，就回答它。如果它构建出的东西和编号的各点不一致，就让它把这个工作流程改成与它们一致，然后再把各步骤读一遍。

读一次运行，看的是每个步骤的状态。一个步骤的内容里可能含有能做出决定的链接，所以你从来不需要打开任何一个步骤。在真实的组织里，只让负责审阅构建的人打开运行历史和 Return Decision Links 数据表，并清理旧的运行。

画面：Apply return decision 工作流程：给审核人发邮件的步骤，然后是等待的步骤
*1“流程运营模块”（FlowOps）。2 给审核人发邮件的步骤。3 等待决定的步骤。*

### 4. 试一次批准

现在按审核人的做法来运行一遍。每一笔测试退货都要使用一个新的订单编号，一个还不在数据表上的编号：退货台是按订单编号来追踪每一笔退货的。

**你输入**：

> 在 Return Requests 中添加一行：Customer name 为 Morgan Ellery，Order reference 为 HB-3001，Item 为 helmet，Condition 为 unopened，Price 为 45，Customer email 为 [你扮演客户所用的地址]。Refund amount、Decision、Decided by 和 Decided at 留空。

**你现在应该会看到**，一个时刻接一个时刻地：

1. 几秒之内，这一行上的 Refund amount 自动填好：45。Decision、Decided by 和 Decided at 仍然为空。在“行动模块”（Actions）>“流程运营模块”（FlowOps）里，Apply return decision 的运行历史多了一次新的运行，这次运行处于暂停状态。创建批准任务和发送邮件的步骤都标示为成功。等待期间，让你的工具只告诉你批准任务的状态和被分配人：它是打开的，并且已分配。

画面：Apply return decision 的运行历史：新的一次运行处于暂停状态
*1“流程运营模块”（FlowOps）。2 Apply return decision 的新运行，已暂停。*

2. 审核人的收件箱里有一封邮件，主题正是你要求的那个。邮件写明这笔退货的事实——客户、订单编号、商品、商品状况、价格和退款金额——以及两个按钮，“批准”和“拒绝”。Return Decision Links 现在有两行，每个按钮一行，Used at 为空。

画面：审核人的邮件，带有“批准”和“拒绝”按钮
*审核人的邮件：这笔退货的事实，以及“批准”和“拒绝”两个按钮。*

3. 打开“批准”。一个页面显示所选的结果：客户、商品和退款金额，以及一个“确认”按钮。什么都没有改变。你愿意的话，可以再打开一次：运行仍然处于暂停，这一行仍然没有决定。

画面：从“批准”按钮打开的确认页面
*确认页面：这笔退货的事实，和一个“确认”按钮。在按下它之前，不会决定任何事。*

4. 按下“确认”。页面显示这笔退货已批准，并说客户正在收到邮件。在“流程运营模块”（FlowOps）里，刚才暂停的那次运行就是完成的那一次，这笔退货没有任何运行还停在暂停状态。在数据表上，这一行现在显示 Decision 为 Approved，Decided by 为 Jordan Vance (confirmed by email)，以及一个 Decided at 时间。客户的收件箱里有一封写明退款金额的邮件，Return Decision Links 上的两行 Used at 都已填好。

画面：Return Requests 数据表滚动到 Decision、Decided by 和 Decided at，由这次运行写入
*1“知识模块”（Knowledge）>“数据表”（DataIQ）。2 由这次运行写入的 Decision、Decided by 和 Decided at。*

画面：Apply return decision 的同一次运行，已完成，它的两个 Send Email (Gmail) 步骤都标示为成功
*1“流程运营模块”（FlowOps）。2 同一次运行，已完成，它的两个“Send Email (Gmail)”步骤都标示为成功。*

5. 回到审核人的邮件，打开“拒绝”。页面显示这笔退货已经做出决定。两个按钮会一起失效，所以一笔退货只会被决定一次。

这是第五个习惯：决定是由发起询问的那次运行写在一行上的一个值——答复、审核人的姓名和时间——不是有人在聊天里打出“看起来没问题”，也不是有人编辑的一个单元格。在有人答复之前，不会有任何东西发给客户，运行只是在等待。

Decided by 显示的是你指定的审核人，后面跟着“(confirmed by email)”：这个决定是从那位审核人自己的邮件里确认的，所以请把这封邮件留在自己手里，不要转发。

如果这一步里有一项检查没有通过，就一个环节一个环节地往回查。Refund amount 填上了吗？Apply return decision 有新的运行吗，它是暂停，而不是失败吗？创建任务和发送邮件的步骤标示为成功了吗？然后看看你的垃圾邮件文件夹。把停在了哪一项检查告诉你的工具，并让它只修这一处。

### 5. 试一次拒绝

把第二笔退货往另一个方向答复。

**你输入**：

> 在 Return Requests 中添加一行：Customer name 为 Riley Okafor，Order reference 为 HB-3002，Item 为 bike lock，Condition 为 used，Price 为 28，Customer email 为 [同一个客户地址]。Refund amount、Decision、Decided by 和 Decided at 留空。

**你现在应该会看到**：

1. 开头和之前一样：几秒之内出现一次新的暂停的运行，审核人的收件箱里有一封带两个按钮的邮件。
2. 打开“拒绝”，然后按下“确认”。页面显示这笔退货已被拒绝。同一次运行从暂停变为完成，这一行显示 Decision 为 Rejected，Decided by 和 Decided at 都已填好。
3. 客户的收件箱里有一封说明这笔退货未获批准的邮件：一段简短的致歉，以及一句请联系退货台的话，没有退款金额。
4. 在同一封邮件里打开“批准”：页面显示这笔退货已经做出决定。这笔退货没有向客户发出任何批准邮件。

## 如何检查是否成功

不要把编程工具对自己所做操作的总结当作证据。一个听起来合理、构建成功的说法很容易编造出来，也很容易被误当真——自己去看一看。其中大部分检查，你在第 4 步和第 5 步里已经做过了。额外的几项是：按钮地址的检查、批准任务状态的读回、一次只问一个人、连接，以及助手。如果你再运行一笔退货，请使用新的订单编号。

### 批准

1. **它会等待。** Apply return decision 的一次新运行在几秒之内进入暂停，它里面创建批准任务和发送邮件的步骤都标示为成功。在这一行上，Refund amount 已填好，Decision、Decided by 和 Decided at 为空。等待期间，让你的工具只告诉你批准任务的状态和被分配人：它是打开的，并且已分配。
2. **一封邮件，没有捷径。** 这笔退货恰好收到了一封邮件，带两个按钮。让你的工具把你收到的那封邮件里的两个按钮地址打印出来，每个代码都缩短显示。每一个都是确认页面的地址，后面跟着 `?t=` 和一个代码，再没有别的东西。请把这些代码留在自己手里。
3. **访问不会决定任何事。** 把“批准”打开两次。你得到的是一个带一个按钮的页面，运行仍然处于暂停，Return Decision Links 上的两行 Used at 仍然为空。
4. **确认才会决定。** 按下“确认”。刚才暂停的那次运行完成了，这笔退货没有任何运行还停在暂停状态。Decision 是 Approved，Decided by 是审核人的姓名，后面跟着“(confirmed by email)”，Decided at 是一个时间，客户的地址收到了写明退款金额的邮件。Return Decision Links 上的两行 Used at 都已填好。
5. **另一个按钮失效。** 在同一封邮件里点“拒绝”，会显示这笔退货已经做出决定。
6. **批准任务与此一致。** 让你的工具只告诉你它的状态：它现在显示已答复，答复为 Approve。绝不要打印它的链接。

### 拒绝

1. **同样的开头。** 一次暂停的运行，和一封带两个按钮的邮件。
2. **拒绝会做出决定。** 按下“拒绝”，然后按“确认”。同一次运行从暂停变为完成。Decision 是 Rejected，Decided by 和 Decided at 都已填好，批准任务显示已答复，答复为 Reject。
3. **没有任何金额发给客户。** 客户的邮件说明这笔退货未获批准：一段简短的致歉，以及一句请联系退货台的话。检查一下里面有没有退款金额——它没有提到任何退款金额，也没有任何等于价格的数字。
4. **没有发出任何批准。** 客户没有收到这笔退货的任何批准邮件，而“批准”按钮现在显示这笔退货已经做出决定。

### 一次只问一个人、连接和助手

- 再添加一笔退货，让它一直等着。这笔退货只用于这项检查，不要答复它。修改它的 Condition。不会有第二封邮件到达，第一次运行仍然处于暂停。可能会出现第二次很短的运行，并立刻完成：那是第 3 步的第 2 点把它拦住了。
- 打开“行动模块”（Actions）>“流程运营模块”（FlowOps）>“更多”>“连接”，确认邮件凭证是一个具名连接，Gmail，而不是某个步骤里的文本。
- 让你的工具把 Return Desk Assistant 的设置读回给你：一项技能，Log return request，没有数据表，所以链接和决定都由工作流程负责。

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

## 接下来做什么

- 留一笔退货不答复。运行会一直保持暂停，等待期间不会有任何东西发给客户。你在第 3 步里要求生成的链接，有效期是七天。
- 用一笔新编的退货，与 Return Desk Assistant 对话，并观察 Apply return decision 的运行历史。在你决定助手记录下来的某一笔退货之前，先把客户的地址填到它那一行的 Customer email 里。
- 阅读[人工批准](../build-it-well/human-approval.md)，了解本课背后的方法：决定放在哪里、什么让关卡真正守住，以及如何证明它从头到尾都接上了线路。
- 参见[构建模块](building-blocks.md)，了解退货台的每一个部分在屏幕上的位置：数据表、工作流程、智能体和邮件连接。
- 关于 SDK、CLI 或 MCP 连接本身的任何内容，[engineer.imbrace.co](https://engineer.imbrace.co/zh-cn) 是保持最新的信息来源——本页的内容会先过时，那个网站不会。[设置你的编程工具](set-up-your-coding-tool.md)有完整的设置说明。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it/working-with-ai.md ====================

---
title: 与 AI 编程工具协作
description: 让 AI 编程工具在 iMBrace 上构建出的成果保持可信的立场、习惯与准则。
level: '2'
track:
- build
verified_on: '2026-09-23'
---

# 与 AI 编程工具协作

现在，大部分在 iMBrace 上的构建工作都可以借助 AI 编程工具完成。这没有问题，而且它几乎不
改变“完成”这个词的含义。这一页讲的，就是真正会改变的那部分。

## 立场

**工具辅助，人来决定。** 这并不是因为工具能力弱，而是因为责任无法转移。必须有人签字确认
这个构建能用，而签字的不能是写出它的那个工具。

**构建对自身的汇报，从不被直接采信。** AI 工具让这一点更加突出：一份令人信服的“测试通过”
总结很容易写出来，却很难和真的测试通过区分开。要亲自运行它、亲眼看着它、到平台上查看结果。
一个你没有亲眼见过的“绿灯”，就不是绿灯。

**如实说明状态。** 一次构建里的每一部分，都只会是以下三种状态之一：

- **已提议**——已经设计，还没有构建；
- **已构建**——已经构建，但还没有在平台上运行并核实；
- **已上线**——已经在平台上运行，并且结果经过人的核实。

没有人会因为停留在“已构建”而被苛责。真正的失败，是把从未运行过的东西写成“已上线”。

## 该给工具什么

- **这份指南的 `AGENTS.md`**，或者管辖你手头这项工作的那一页——不要一次给全部内容：一个
  把所有东西都读了一遍的工具，留给你这个问题的空间反而更少。
- **SDK 自己的地图**，在它编写 SDK 代码时，从
  [engineer.imbrace.co](https://engineer.imbrace.co/llms.txt) 现抓现用，绝不用旧的副本。
- **组织本身**，通过 MCP 连接，用在“这里存在什么”或“发生过什么”这类问题上——见
  [设置你的编程工具](set-up-your-coding-tool.md)。

## 准则

- **工作流程、代码步骤、提示词或已提交的文件里都不能出现凭证。** 凭证只存放在组织自己的
  连接存储中，或者存放在一个绝不提交的本地 `.env` 文件里。
- **代码步骤是纯函数**——数字进去，结果出来，没有网络调用，没有密钥——如果做不到，就
  明确说明原因。
- **拒绝回答本身也是一种数据，不是错误。** “我没找到”是一个有效、有用的答案。
- **被跳过的检查绝不算通过。** 如果一项测试没能运行，就如实说它没有运行。
- **测试数据、日志、提示词或示例中都不能出现个人数据。** 都用虚构的。
- **写给一个陌生人看。** 用平实的句子，不用只有当事人才懂的简写或黑话。

## 最重要的几个习惯

1. **业务成果优先。** 谁会用它、今天卡在哪里、它能带来什么——一个漂亮地回答了没人问过
   的问题的方案，就是一个错误的方案。
2. **人先画草图。** 在工具提出设计方案之前，先让人把用例画出来——形状、各个部分，以及
   哪里由人来做决定。这样设计才始终属于这个人。
3. **带着证据表达不同意见。** 当工具认为这个人错了，它应立即说出来，并给出证据，而不是
   默默按要求去做。
4. **每一个论断都要有依据。** 一条数据表记录、一次运行的 id、一段粘贴出来的输出——没有
   依据，就不能下论断。
5. **改正记录时要注明日期。** 当一条发现或一条决策记录后来被证明是错的，就地注明日期
   说清楚，并保留原文可见。
6. **由另一个人来评审。** 在发布之前，由没有参与构建的人跑一遍
   [评审清单](../build-it-well/review-checklist.md)。
7. **流程的繁简要与改动的大小相称。** 一次小改动，只需要一条小记录。

## 让委派保持浅层

如果你的工具把工作交给了它自己的助手，就把交接控制在最上一层，给每个助手一份完整的任务
说明，并亲自核实每一个结果：当某个助手说它修好了什么，就打开文件亲自看一看。

## “完成”意味着什么

另一个人能够安装使用的成果、一份他们能照着做的说明、一个他们能运行的测试，以及对每个部分
如实标注的状态。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it/building-blocks.md ====================

---
title: 构建模块
description: 认识每一个 iMBrace 构建都由哪五个部分组成，以及扩展和交付它们的三种方式——记住每一个的名称，也记住它在界面上的位置。
level: '2'
track:
- build
verified_on: 2026-09-29
---

# 构建模块

iMBrace 上的每一个用例，不论外观差异有多大，都是用同样的五样东西搭建起来的：一张数据表、一个智能体、一个文档模型、一个工作流程和一个渠道。本页将逐一说明它们的名称、用途，以及它们在产品中的位置，让你第一次打开培训组织时，侧边栏上的一切都不再陌生。最后还会介绍扩展这些部件、或把它们交给别人使用的三种方式：技能、MCP 连接，以及安装模块。

## 数据表

数据表是一张由你自行定义结构的表格——有行，也有按类型定义的字段，就像一张轻量版的 CRM 表格。它用来保存构建工作需要记住的任何内容：一份退货申请清单、一份已报价的报价单、一组可供他人自行编辑的规则。

在侧边栏中，它位于**“知识模块”（Knowledge）>“数据表”（DataIQ）**下（SDK 与其权限范围中称之为 board，或 databoard；产品在屏幕上显示的名称是 DataIQ）。其余每一个构建模块都会读写数据表：工作流程的每一个步骤、智能体唯一可调用的那个精简工具，以及文档模型自身的提取结果，最终都会落在同一张数据表上。

画面：数据表以行与带类型字段的形式打开
*1 “知识模块”（Knowledge）>“数据表”（DataIQ）。2 数据表以行与带类型字段的形式打开。*

让数据表值得信赖的习惯：把业务人员可能需要调整的规则——阈值、费率、上限——作为可编辑的行放在数据表上，而不是写死在智能体自己的指令里。[八项原则](../build-it-well/the-eight-principles.md) 说明了原因。

用代码实现：[数据表](https://engineer.imbrace.co/zh-cn/reference/board/)。

## 智能体

智能体是用户或渠道所对话的前端。它负责进行对话本身：理解对方在请求什么，并调用正确的工具来完成它。

在侧边栏中，它位于**“行动模块”（Actions）>“AI智能助手”（AgentIQ）**下。用户要通过渠道才能联系到智能体，它的行动方式是调用一个工作流程——也就是它的其中一项技能，下文会介绍——数据表的读写实际上都发生在这一步。

画面：AI智能助手的“启用中的 AI”标签页，每张卡片一个助手
*1 “行动模块”（Actions）>“AI智能助手”（AgentIQ）。2 AI智能助手的“启用中的 AI”标签页，每张卡片一个助手。*

让智能体值得信赖的习惯：只给它一个专用于某件事的精简工具，绝不给它整张数据表的权限，这样它可以记录一项申请，却永远无法自己写下批准该申请的决定。[人工批准](../build-it-well/human-approval.md) 说明了为什么智能体绝不能自己写下那个决定。

用代码实现：[智能体](https://engineer.imbrace.co/zh-cn/reference/ai-agent/)。

## 文档模型

文档模型告诉提取功能要从文件里提取什么内容。它的作用是把一份非结构化的文档——发票、表单、扫描的装箱单——转换成数据表可以保存的结构化字段。

在侧边栏中，它位于“知识模块”下的**“文档模块”（DocIQ）**，在**“文档模型”（Document Models）**标签页中。它提取出的内容会以行的形式落在数据表上，也就是工作流程或智能体随后读取的那张数据表。

画面：文档模块的“文档模型”标签页，展开其中一个模型的提取字段
*1 “文档模块”（DocIQ） > “文档模型”（Document Models）。2 文档模块的“文档模型”标签页，展开其中一个模型的提取字段。*

让文档模型值得信赖的习惯：先采用平台自带的默认模型，再考虑另写新模型，并让提取功能对准某一张数据表本身的字段，而不是把模型的选择交给运气。[文档模型](../build-it-well/document-models.md) 说明了应该按什么顺序尝试。

用代码实现：[Document AI](https://engineer.imbrace.co/zh-cn/sdk/document-ai/)。

## 工作流程

工作流程（也叫 flow）是一串一旦被触发就会自动运行的步骤。它用来完成实际的工作，并且按固定、可核对的顺序进行：读取数据表、执行计算、等待人工做决定、发送消息。

在侧边栏中，它位于**“行动模块”>“流程运营模块”（FlowOps）**下（SDK 与其权限范围中称之为 workflow；产品在屏幕上显示的名称是 FlowOps）。工作流程会读写数据表，可以是智能体调用的那一个工具，既能由渠道事件触发启动，也能同样轻松地由数据表的变化触发启动。

画面：流程运营模块的工作流程列表
*1 “行动模块”>“流程运营模块”（FlowOps）。2 流程运营模块的工作流程列表。*

让工作流程值得信赖的习惯：优先用平台自带的现成步骤搭建，如果确实需要自己写步骤，就保持它的纯粹——只基于传入的值进行计算，不持有任何自己的凭据。[原生优先](../build-it-well/native-first.md) 说明了这样做的好处。

用代码实现：[工作流程](https://engineer.imbrace.co/zh-cn/reference/workflow/)。

## 渠道

渠道是用户实际联系到智能体的地方——网站聊天窗口、WhatsApp、电子邮件，或其他已连接的消息应用——它也是回复送达的地址。

在侧边栏中，它位于“行动模块”下的**“连接模块”（ConnectIQ）**，在**“渠道设定”（Channels）**标签页。渠道是与智能体对话开始的方式，工作流程也可以把渠道的某个事件当作自己的触发条件。

画面：连接模块的“渠道设定”标签页，列出网页小部件和各消息渠道
*1 “连接模块”（ConnectIQ） > “渠道设定”（Channels）。2 连接模块的“渠道设定”标签页，列出网页小部件和各消息渠道。*

让渠道值得信赖的习惯：把它的登录信息作为组织自己的一个连接来设置一次，绝不把它当作一个值放进工作流程里。需要有人登录的连接（例如托管邮件服务）由一个人为整个组织设置一次；邮件服务器连接则用服务器自身的信息配置一次即可。[原生优先](../build-it-well/native-first.md) 说明了为什么流程中绝不应该携带任何凭据。

用代码实现：[渠道](https://engineer.imbrace.co/zh-cn/reference/channel/)。

## 扩展与交付它们的三种方式

### 技能——智能体能做什么

技能是把一个工作流程交给智能体，作为一个它可以调用的具名工具。它的作用是扩展智能体在对话之外真正能做的事——记录一行数据、查询某项信息、执行一次计算——但始终通过工作流程来完成，绝不直接把数据表交给智能体。

在智能体的设置画面中，技能位于**“行为设置”（Behavior Settings）**标签页里的**“功能”（Skills）**区块（屏幕上标为“功能”，也就是本课程所说的技能；SDK 的完整流程指南把这些称为工具，归在 Workflows 之下）。在此添加一个工作流程后，智能体就可以在对话中调用它；它的描述文字，就是智能体用来判断此刻是否该调用它的依据。

画面：AI智能助手的“行为设置”标签页，其“功能”列表
*1 “行为设置”（Behavior Settings）。2 AI智能助手的“行为设置”标签页，其“功能”列表。*

用代码实现：[完整流程指南](https://engineer.imbrace.co/zh-cn/sdk/full-flow-guide/)。

### MCP 连接——编程工具如何查看组织

MCP 连接让 AI 编程工具能够直接查看并更改一个组织，而不是靠别人转述来了解它。它是用来构建的：把编程工具指向它，给出一个地址和一个密钥，它就能在写下任何一行代码之前，列出已经存在哪些数据表和工作流程。

在侧边栏中，它位于“行动模块”下的“连接模块”，在**MCP**标签页，点开后就是你原本会直接去读的那份指南：[engineer.imbrace.co/mcp/overview](https://engineer.imbrace.co/zh-cn/mcp/overview/)。[设置你的编程工具](set-up-your-coding-tool.md) 一步步演示了如何用这种方式把编程工具连接到测试组织。

画面：连接模块的MCP标签页，打开MCP连接指南
*连接模块的MCP标签页，打开MCP连接指南*

用代码实现：[MCP 服务器指南](https://engineer.imbrace.co/zh-cn/mcp/overview/)。

### 安装模块

安装模块会把一整个用例——它的工作流程、智能体设置和数据表——作为一个整体包，一步复制进某个组织。它交给对方的是一个可以直接使用的起点，而不是一份需要手动照做的说明书。你的 iMBrace 联系人会把模块安装进你的组织。

安装完成后，它的数据表、工作流程和智能体会出现在各自平常的画面上——数据表、流程运营模块和 AI智能助手——管理员可以像对待组织里其他任何东西一样查看和编辑它们。若只需要单个智能体，**AI智能助手**下还有一个**“市场”（Marketplace）**标签页，里面有现成的智能体模板可供使用。

画面：AI智能助手的“市场”标签页，提供现成模板
*1 AI智能助手 > “市场”（Marketplace）。2 AI智能助手的“市场”标签页，提供现成模板。*

用代码实现：[SDK 总览](https://engineer.imbrace.co/zh-cn/sdk/overview/)。

## 它们如何协同运作

教程和[让它等待人的决定](make-it-wait-for-a-person.md)中，Harbor Bicycle Co. 的退货台，一次性用到了所有构建模块。客户与 Return Desk Assistant 对话。这个智能体负责倾听，它唯一的技能——一个叫 Log return request 的工作流程——会在 Return Requests 数据表上写入新的一行。第二个工作流程根据 Refund Rules 数据表算出退款金额。还有一个工作流程去询问值班经理：它通过邮件发出一张带有“批准”（Approve）和“拒绝”（Reject）按钮的卡片，然后等待。每个按钮都会打开一个页面，由经理在上面确认；随后这个工作流程从暂停的地方接着往下走，把决定、审核人的姓名和时间记录在这一行上，并给客户发邮件。这个场景不需要用到文档模型，因为没有任何东西是以文件形式进来的——如果退货是以扫描装箱单的形式进来，就会先由文档模型读取，再以一行的形式落在同一张数据表上。

Harbor 的每一个构建模块，都可以打包成一个模块，安装进另一个组织，它的数据表、工作流程和智能体设置会一起带过去，让那个组织自己的管理员打开并调整。而最初让编程工具搭建出这一切的那同一个 MCP 连接，之后也能用来检查结果：列出数据表，读取工作流程最近一次的运行记录。

想亲手搭建一遍，一步一步来，请见[教程](vibe-coding-tutorial.md)，然后在[让它等待人的决定](make-it-wait-for-a-person.md)里，让退货台去等待一个人的决定。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/index.md ====================

---
title: 构建得好
description: 要设计出一个经得起真实使用、真实负载和真实监督考验的 iMBrace 构建，需要具备什么。
level: '3'
track:
- build
verified_on: '2026-09-23'
---

# 构建得好

一次演示只能证明某样东西能跑通一次。构建得好，意味着它能持续运行：面对真实数据、承受真实负载、真正有人参与其中，而且不需要靠任何人时刻提醒自己要小心。

这与写更多代码无关。让一个构建变得扎实的，大多是你在动手写任何代码之前就做出的设计选择：用哪些部件组装它、在哪个环节由人批准、哪些工作交给平台自身的能力而不是自定义代码完成，以及哪些东西绝不能离开该构建自己的配置。

## 八项原则，一句话概括每一项

1. **可溯源性（Provenance）**——答案中的每一个数字都能追溯到它的出处，否则答案就会直接说明数据中没有这项信息。
2. **确定性（Determinism）**——由 AI 来判断适用哪一条规则；规则本身以数据形式存在，人可以编辑；运算始终以同样、可靠的方式完成。
3. **模块化（Modularity）**——构建由多个部件组装而成，每个部件只做一件事、有明确的契约，而不是一大团纠缠不清的自定义逻辑。
4. **无领域内核（Domain-free cores）**——可复用的逻辑不带客户名称、不带具体业务细节；凡是特定于某一家公司的内容，都以配置的形式传入。
5. **人的治理（Human governance）**——一个真实的决定是一项被记录下来的事实——谁决定的、决定了什么、什么时候决定的——而不是在聊天窗口里随手打出的一句“好的”。
6. **原生优先（Native-first）**——先用平台已经提供的能力，再考虑写自定义代码；构建中的任何部分都不应保存登录凭证。
7. **可运维性（Operability）**——构建可以被重置、被测试、被独立核查，而不只是由构建者自己运行过一次。
8. **安全与主权（Security and sovereignty）**——凭证、密钥和敏感数据都留在配置中，绝不进入构建自身的逻辑。

## 这一页讲什么，其余页面讲什么

| 页面 | 内容 |
|---|---|
| [八项原则详解](the-eight-principles.md) | 每项原则的完整说明：它的含义、做得好是什么样子、常见的出错方式，以及你该向自己的构建提出哪些问题。 |
| [用例形态](use-case-shapes.md) | 业务用例反复出现的九种形态，以及每一种通常由哪些部件组装而成。 |
| [人工批准](human-approval.md) | 一个人如何从带有“批准”和“拒绝”按钮的邮件做出决定，并在页面上确认——以及为什么聊天回复不算是一项决定。 |
| [原生优先](native-first.md) | 为什么要先用平台自身的能力、再考虑写代码，以及这样做能带来什么好处。 |
| [文档模型](document-models.md) | 如何选择让“文档模块”（DocIQ）从文档中提取什么内容：优先采用默认模型，其次扩展它，最后才考虑自己编写。 |
| [反模式](anti-patterns.md) | 反复出现的构建错误、每一种的代价，以及对应的修复方法。 |
| [审查清单](review-checklist.md) | 同样的八项原则审查，做成一份清单，供你在交付前对照自己的构建逐项核查。 |

这些都不需要死记硬背。找到与你眼前这个决定相匹配的页面，用它提供的问题来检视，然后继续前进。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/the-eight-principles.md ====================

---
title: 八项原则
description: 一个能经受真实使用考验的构建背后的八项原则——每一项原则的含义、做得好是什么样子，以及常见的出错方式。
level: '3'
track:
- build
verified_on: '2026-09-30'
---

# 八项原则

有八个理念，把“只能成功一次的构建”和“能够持续运行下去的构建”区分开来。它们都不需要什么
特殊的技术。大多数只是关于一段逻辑应该放在哪里、由谁来修改它的决定。

## 1. 可溯源性（Provenance）

**含义。** 答案中出现的每一个数字，都能追溯到它的出处；如果数据中没有这项信息，答案就应该
直接说清楚。一个没有出处的数字，并不是“便宜版”的有出处数字——它是另一种完全不同的东西，而
这种差别在有人据此采取行动之前，是看不出来的。

**做得好是什么样子。**
- 答案中的每一个数字，都附有它所依据的记录，以及数据截至的日期。
- 每一条引用的文字，都会与它声称出自的文档进行核对，答案会说明它出现在该文档的哪个位置。
- 当数据中没有答案时，回复会直接说明这一点，绝不会编造一个数字来填补空缺。
- 每一类答案都有固定的格式——用哪些数字、来自哪些来源、按什么顺序排列。固定的格式能挡住
  编造的数字，而仅靠成文规则做不到这一点。

**常见的出错方式。**
- **自信满满的总结。** 一个由 AI 生成、读起来很顺的数字，背后却什么依据都没有。它之所以能
  蒙混过审核，恰恰是因为读起来很顺。
- **装饰性的溯源。** 来源列表只写出了文档名称，却没有指明具体的行或段落，导致没有人能在不
  重做一遍工作的情况下真正核实这个数字。
- **被悄悄软化的结论。** 一个已被标记的问题，在之后的处理中被悄悄降级，没有人注意到它发生
  了变化。
- **只是“存在”的引用。** 核实一条引文出现在原文中，只能证明这句话确实存在，不能证明它支持
  了引用它所要论证的结论。

**该问自己的问题。**
1. 从最近一份答案中任选一个数字。你能不问搭建这套系统的人，就追溯到它的出处记录吗？
2. 答案是否带有一个“截至日期”？
3. 找一条引文。系统能证明它出现在原文中，并说出具体位置吗？
4. 当数据无法回答某个问题时，用户实际看到的是什么？
5. 每一条引文，是真的支持它所附着的结论，还是仅仅出现在原文里而已？

## 2. 确定性（Determinism）

**含义。** 由 AI 来判断该套用哪一条规则；规则本身以数据的形式存在，人可以读取和修改它。运算
永远按同一种方式进行。任何有实质影响的结果，都不会只在 AI 自己的推理过程里算出来；同一个问题
问两遍，得到的答案应当一样。

**做得好是什么样子。**
- 运算始终经过同一个专门的计算步骤，每一项输入都清楚可见。
- 规则以人可以编辑的行或字段形式存在，因此修改一个阈值不需要开发者，也不需要发布新版本。
- 一条系统尚未实现的规则，会干脆地拒绝执行，而不是被悄悄跳过或凭空猜测。

**常见的出错方式。**
- **写进提示词里的规则手册。** 把限制、标准或阈值写进 AI 的指令里，谁都无法编辑、引用或
  审计它们。
- **可以绕过的计算器。** 没有任何机制强制 AI 使用专门的计算步骤，于是在压力较大时它会自己算
  出结果——通常是对的，直到某次悄悄地算错。
- **混在一起的规则。** 系统自动套用的数字，和 AI 应当原样引用的措辞，被存放在一起，让人分不
  清哪个是哪个。
- **反向表述的规则。** 一条以“不得发生什么”的方式写出的规则，无论是人还是模型都很容易理解
  反。把每条规则写成你想看到的那个条件，并且把一个“二选一”的要求当作一条规则来处理，而不是
  拆成两条。

**该问自己的问题。**
1. 输出中的每一个数字，具体是在哪里算出来的？
2. 业务人员能不能不找开发者，自己修改一个阈值或限制？
3. 把同一个问题问两遍，两次的答案是否完全一致？
4. 当系统遇到一条它还没被教过的规则时，现在会发生什么？

## 3. 模块化（Modularity）

**含义。** 一个构建是由多个部件组装而成的，每个部件都有明确的职责和明确的接口约定，而不是
一大团纠缠不清的定制逻辑。只有当两个各自独立、指名道姓的用途，都在原样使用某样东西时，它才
算得上“共享”——而不是因为它看起来可以复用。

**做得好是什么样子。**
- 每个部件只做一件事，有明确定义的输入和输出，并且可以单独测试。
- 一个被称为“共享”的部件，确实有两个真实的使用方在原样使用它，其中至少一个用途并不是它最
  初被搭建出来时所针对的那个。
- 两个内部细节被改动过的版本，老老实实地算作两个不同的部件，而不是假装成一个通用部件。

**常见的出错方式。**
- **靠愿望撑起来的“共享”。** 一个被标注为可复用的部件，实际上只有一个真实使用方，于是下
  一个团队继承了一个从未真正成立过的承诺。
- **分叉出来的副本。** 第二个版本只是需要再调整一点，于是有人直接复制了整个部件，而不是把
  它参数化。现在需要维护两样东西，却共用一个名字。
- **没有使用方的部件。** 因为看起来“大概用得上”而被搭建出来，从此被永远维护下去，实际最多
  只被用过一次。

**该问自己的问题。**
1. 找一个被标注为“共享”的部件，说出它两个真实、各自独立的使用方是谁。
2. 有没有哪个“变体”，实际上是靠改动核心逻辑、而不是靠改动配置来实现差异的？
3. 一个部件能不能在不依赖真实账户或网络连接的情况下，单独完成测试？
4. 这个构建里，有没有什么东西没有真实、指名道姓的使用方？它为什么还存在？

## 4. 无领域内核（Domain-free cores）

**含义。** 一个构建核心处可复用的逻辑——智能体的核心指令、一项共享技能——不带任何客户名称，
不带具体的业务流程，不带任何只属于某一家公司的细节。凡是特定于某一家公司的内容，都以配置的
形式随核心一起提供，而不是被写死在核心里面。

**做得好是什么样子。**
- 核心读起来像是在描述一个角色或一项职责，而不像是把某一家公司的流程写成了文字。
- 每一处特定于某家公司的细节，都通过配置传入，核心本身不包含任何超出该配置所声明范围的
  内容。
- 同一个核心，只需更改配置，就能服务于另一家公司或另一个行业，不需要对核心本身做任何改动。

**常见的出错方式。**
- **写死进去的业务。** 一段提示词或一段逻辑里，带着某一家公司的产品列表、专用术语或流程，
  一旦该公司的数据发生变化，它就立刻过时了。
- **通用部件里出现的公司名字。** 一个以某笔交易或某个客户命名的部件，下一个团队若不重新命
  名、重新改写，就无法复用它。
- **说谎的配置。** 有些设置项被声明了，核心却从未真正用到；有些则被核心用到了，却从未被声
  明过——结果没有人能说清楚核心到底依赖什么。
- **写死的地址。** 把某台机器的网络地址写进了工作流程里。这会把构建与某一个网络绑死，一旦要
  迁移部署，就得逐个找出并修改所有用到它的步骤。应当用部署自身内部的名称来指代各项服务，并
  向负责运行该部署的人确认这些名称。

**该问自己的问题。**
1. 在核心逻辑里搜索公司名称、账户标识符，或任何特定于某个客户的术语，结果会找到什么？
2. 这个核心能不能只靠更改配置，就服务于另一家公司或另一个行业？
3. 配置里的每一项设置，核心是否都真的用到了？核心有没有用到任何配置里没有声明的东西？
4. 有没有哪个工作流程里，包含着某台机器的网络地址？

## 5. 人的治理（Human governance）

**含义。** 一个关卡，就是针对某一具体事项、被记录下来的决定——谁做的决定、决定了什么、什么
时候做的——而且一旦出现异常，它默认拒绝放行，而不是默认放行。没有记录在案的决定，就没有任
何输出会被放出去。人默认在自己本来工作的地方做决定——一封带有“批准”和“拒绝”按钮的邮件，每个按钮都会打开一个确认页面；但“决定必须被记录下来”这一点不是可选的。

**做得好是什么样子。**
- 关卡会依据底层数据自己算出答案，而不是直接相信 AI 在同一轮对话里刚说过的话。
- 决定被记录下来时，包含谁做的决定、决定了什么、什么时候做的——由系统本身捕获记录，而不只是在聊天记录里看得到。
- 人在自己本来工作的地方做决定，文档就在眼前：一封按钮会打开确认页面的邮件。仅仅打开链接，不会决定任何事；只有页面上的“确认”才会。
- 任何有实质影响的事项都不会被自动批准。缺少决定会拦住输出，而不是默认放行。
- 这次请求会让流程暂停，而不是终止它。一旦决定落定，同一次运行会自行继续下去——完成任务，
  或者把结果告知发起请求的人——不需要任何人再回来重新问一遍。

**常见的出错方式。**
- **背后空无一物的关卡。** 一个本该由人来更新的状态字段，实际上没有任何东西在监听它、对它的变
  化做出反应。它看起来像是有监督，实际上什么监督都没有。
- **填在单元格里的决定。** 人被要求在数据表里选一个值来批准。那个值藏在一张他们没有理由打开的表格里，要保存后才会生效，也让人感觉不像是在做决定。
- **一打开就做出决定的链接。** 一个只要被访问就会记录决定的按钮，会被第一个打开它的邮件扫描程序或预览功能替人做出决定。
- **对话里的“好”。** 一个人对着 AI 打出“好”字，却没有任何持久的记录留下，于是这个决定只存
  在于一份再也不会有人翻看的聊天记录里。
- **轻信的关卡。** 审批环节直接读取 AI 提出的数字，而不是自己独立算出来，结果一个错误的数字
  也能让自己获得批准。
- **自我批准的智能体。** 智能体能够通过它做其他一切事情所用的同一个工具，自己写入决定——状
  态、批准结果、决定人。记录决定的这些列，应当在记录创建时就取好初始值，此后拒绝智能体的任
  何写入。
- **被当作“通过”的缺失结论。** 一项尚未运行、或已经失败的检查，会让记录看起来和真正通过的
  记录一模一样。应当给每一条记录都打上明确结论——连没问题的记录也不例外——并让此后的每一步
  都等待这个结论，没有它就拒绝继续。
- **问完就挂起的请求。** 决定被记录了下来，但之后没有任何环节继续推进。发起请求的人得自己留
  意并主动跟进。

**该问自己的问题。**
1. 找出最近一次决定的记录。是谁、决定了什么、什么时候？
2. 如果审核人当时联系不上，会不会仍有东西被放出去？
3. 这个关卡是自己算出答案，还是直接相信别人递过来的数字？
4. 审核人本来在哪里工作、他们看到什么？那条路径是否曾以那个人的身份端到端走通过？仅仅打开链接，会不会决定任何事？
5. 如果同一个决定被提交了两次，会发生什么？
6. 智能体能不能写入那些记录决定的列？
7. 当检查还没有给记录打上结论时，后面的步骤会怎么做？
8. 分别试一试批准、拒绝，以及放着不管不处理。在每一种情况下，流程是否都会自行继续下
   去——完成任务，或者把结果报告出来——不需要任何人问第二遍？

参见[人工批准](human-approval.md)，了解人如何从一封邮件做出决定、确认页面做了什么，以及为什么单凭聊天回复算不上一项决定。

## 6. 原生优先（Native-first）

**含义。** 如果平台已经提供了完成某件事的方式——搬运数据、发送消息、等待某个人处理、连接到
另一个系统——就用平台提供的方式，而不要自己写自定义代码去做同样的事。如果你能
明确说出某项能力“这是平台的一个功能”，那么用自定义代码把它重新做一遍，只会把这项
能力藏起来、随着时间推移而老化，并且通常最终还需要一个内置方式原本根本不需要的凭证。

**做得好是什么样子。**
- 构建是由平台自身的构件一步步搭起来的，非开发者也能看懂。
- 与其他系统的连接，保存在平台自身的连接存储里，权限范围明确、可以复用，绝不会被嵌入到构
  建的逻辑内部。
- 在确实需要自定义代码的地方，它只对拿到的输入做计算，不会自作主张地去调用其他任何东西。
- 任何例外情况都被记录下来：考虑过哪项能力、为什么没有使用它，以及满足什么条件就可以把这
  段自定义代码退役。

**常见的出错方式。**
- **自建捷径。** 用自定义代码去做平台本来就已经提供的事，通常是因为事先没有人查证
  过。它往往需要一个内置方式本不需要的凭证，而且构建一旦搬到别处，它就会立刻失效。
- **被包装过的脚本。** 一大段自定义逻辑，外面只裹着薄薄一层 AI。它能算出正确答案，却完全说
  明不了这个设计本身是否站得住脚。
- **悄无声息的凭证。** 一个登录信息或密钥被嵌在构建的某个角落，没有人记录下来，于是也就没
  有人再回头把它清理掉。

**该问自己的问题。**
1. 打开这个构建，一个非开发者能不能说出每一步在做什么？
2. 在构建里搜索任何看起来像凭证或访问密钥的东西，结果会找到什么？
3. 对每一段自定义代码：当时考虑过平台的哪项能力，为什么它不够用？
4. 把这个构建搬到另一个账户或环境中，会有什么东西失效？

更多内容见[原生优先](native-first.md)。

## 7. 可运维性（Operability）

**含义。** 让构建持续运行，是搭建它的一部分，而不是事后才想起来补的东西：要有办法把它重置
回一个已知状态，要有一套固定的测试用例可以拿来打分，构建的每一种模式都要真正被跑过一遍，还
要有第二道独立的核查，检查第一道工作的成果。

**做得好是什么样子。**
- 构建的每个部分，都有一项不需要真实账户或凭证就能运行的测试，而且这些测试会在任何东西上
  线之前自动运行。
- 一套固定的测试用例，每次都按同样的方式打分；跑不了的用例会被报告为“跳过”，绝不会被悄悄
  算作“通过”。
- 第二道独立的核查会审查主流程，并标记出分歧之处，而不是自己悄悄把它们改掉。
- 构建可以在平台内部被重置回起始状态，而不是靠某个人从自己的笔记本电脑上手动恢复。
- 工具返回的错误信息简短，每一段对话的长度都控制在运行它的模型的上下文范围之内。

**常见的出错方式。**
- **没人看见的绿灯。** 一份“测试通过”的报告，是被粘贴进来的，而不是被真正盯着跑完的。
- **各算各的分。** 每个构建都自己发明一套比对结果与预期的方法，于是任何两份报告出来的分
  数，含义都对不上。
- **重置不了的演示。** 一个只能成功运行一次的构建，之后必须由它的作者亲自动手重新拼好，才
  能再演示一遍。
- **未经核查的通过。** 一个结果之所以被相信，仅仅是因为从来没有别的东西核查过它。
- **把状态当成结果。** 一个步骤的状态告诉你的是这一步运行过了；它本该产出的那条记录，告诉
  你的才是工作真的完成了。要核查的是那条记录。
- **被信任的标准答案。** 测试的标准答案是人写出来的，也可能是错的。当一个结果与标准答
  案不一致时，也要检查一下标准答案本身，并同时按原始标准答案和修正后的标准答案两个版本来报
  告结果。

**该问自己的问题。**
1. 你是不是亲自运行了这些测试，并且亲眼看着它们通过？
2. 那套固定的测试集在哪里，最近一次打分是什么时候？
3. 重置这个构建，它是否会精确地回到同一个状态？
4. 是什么在独立核查主流程，它最近一次发现分歧是什么时候？
5. 一个没有参与搭建的人，能不能仅凭安装包和文档，就把它装起来、跑起来？
6. 对每一步而言，是哪一条记录证明了这项工作真的发生过？

## 8. 安全与主权（Security and sovereignty）

**含义。** 在这样的平台上，一个凭证是能打开很多东西的钥匙，而不是打开某个小地方的一个密
码。要这样对待它：严格限定权限范围，保存在配置里，绝不嵌入构建自身的逻辑，绝不提交进共
享文档，也绝不作为工作上下文的一部分，交给 AI 编程工具。

**做得好是什么样子。**
- 构建通过平台自身的连接来访问其他系统，因此它的逻辑里完全不包含任何凭证，可以安全地分享
  或迁移。
- 任何刻意为之的例外，都被记录在构建本身上，写明它是什么、满足什么条件就能不再需要它。
- 自动化检查会在任何东西上线之前，拦下其余的问题：没有形似凭证的文本，没有内部机器名称或
  文件路径，没有个人联系方式。
- 敏感字段的脱敏，由平台本身在底层数据上强制执行，而不是靠逻辑里一个可能被跳过或遗忘的步
  骤。存放原始、未脱敏标识符的存储，绝不会与任何 AI 连接在一起。
- 哪些 AI 模型可以读取数据，是按每个部署、每个组织分别设定的。在个人数据被录入之前，要向负
  责运行该部署的人确认：它所使用的每一个模型——无论用于对话、读取文档还是搜索——都运行在部
  署内部。

**常见的出错方式。**
- **图方便的捷径。** 为了回答一个棘手的问题，临时把存放原始敏感数据的存储直接连到 AI 上。两
  者之间的隔离本来就是整个保障所在，而它就这样被悄悄打破了。
- **导出包里的凭证。** 一个共享出去的包，之所以能用，是因为里面带着一个正式凭证，而它被交
  给了团队之外的人。
- **分不清的凭证。** 整个流程里，没有任何标记能把用完即弃的测试凭证和正式凭证区分开来，结
  果构建可能用错了凭证。应当给测试凭证和正式凭证打上不同的标签，并在分享或运行一个构建之
  前，先确认它手里拿的是哪一种。
- **未经检查的导出。** 没有先打开看一眼，就把一份导出分享了出去。应当在每一份导出离开团队
  之前打开检查，确认里面不含凭证、不含客户数据、也不含个人信息。
- **发送给 webhook 的凭证。** 运行历史会保留每次运行的输入，以便日后可以回顾——这正是凭证绝
  不该出现在 webhook 调用里的原因。应当发送一个标识符，让工作流程去使用一个已保存的连接。

**该问自己的问题。**
1. 在即将分享出去的所有内容里，搜索任何看起来像凭证的东西，结果会找到什么？
2. AI 编程工具能访问到的凭证，是不是一个权限有限、用完即弃的凭证？
3. 敏感字段的脱敏，是由平台强制执行的，还是靠一个有人可能会跳过的步骤？
4. 谁能看到原始的、未脱敏的数据？究竟是什么在阻止 AI 被连接到这份数据上？
5. 你上一次分享给别人的包，里面实际上装了什么？
6. 有哪些 AI 模型会读取这个构建的数据？其中有没有哪一个是在部署之外的？

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/use-case-shapes.md ====================

---
title: 用例形态
description: 业务用例在 iMBrace 上反复出现的九种形态，以及每一种通常由哪些部件组装而成。
level: '3'
track:
- build
verified_on: '2026-09-30'
---

# 用例形态

大多数业务用例之间的差异，并不像乍看之下那么大。见得多了，就会发现它们能归纳为数量不多的几种反复出现的形态。找到与你手头问题相符的形态，你就有了一份可以组装的初稿——一个可以拿来讨论、而不是最终定案的设计。

下面每一种形态，先说明它看起来是什么样子，再说明它通常由哪些部件组装而成。这里说的是部件的种类和作用，而不是具体的产品——真正的构建部件在平台自身的部件库中。

## 1. 交易处理器

**它是什么样子：** 有人用大白话提出请求，想要一个报价或配置好的东西——一份报价单、一次预订，或者为他们量身核算出的具体方案。

**通常由以下部件组装而成：**
- 一个针对此类交易调优过的智能体
- 一项查找现有记录的技能
- 一项搜索匹配记录的技能
- 一项执行计算、并展示所用全部输入的技能
- 一项保存结果记录的技能
- 一项根据模板生成文档的技能
- 一项在任何内容发出之前，先通过带确认页面的邮件请人批准的技能
- 一项将完成的文档发送给请求人的技能
- 在容量有限的场景下，一项按真实剩余可用量（而不仅仅是原始数量）预留名额的技能

## 2. 信息提取后台

**它是什么样子：** 单据不断送达——发票、申请表、表单——需要被核对后变成结构化的记录。

**通常由以下部件组装而成：**
- 一个读取传入文档的智能体
- 平台自带的文档接收功能
- 一项在读取前把文档拆分成各个独立部分的技能
- 一项将一条记录与另一条记录进行比对的技能，包括涉及第三方来源时的三方核对
- 一项按规则核对提取值的技能
- 一项查找重复记录的技能，即便写法略有不同也能识别
- 一项保存记录的技能
- 一项在任何未能明确通过时请人做出决定的技能
- 一项发送结果消息的技能
- 一轮独立的复核，用来审计第一轮处理的结果

## 3. 数据洞察台

**它是什么样子：** 人们用大白话就企业内部已有的数据提出问题。

**通常由以下部件组装而成：**
- 一个专为回答数据类问题而构建的智能体
- 一项查询底层记录、并返回其实际执行的查询语句（而不只是给出一个看不到推导过程的答案）的技能
- 一项对记录进行分组汇总的技能
- 一项执行计算的技能
- 一项通过邮件发送答案的技能
- 一项自动化，在新记录一出现就将其关联回其父记录

当某个数字必须可核实时，使用上面的查询技能——它会连同答案一起返回其执行的查询语句，方便任何人事后核对这个数字。

## 4. 对话式入口

**它是什么样子：** 任何人都可能从某个渠道进来——一个聊天小组件、一款消息应用、一个收件箱——构建必须先弄清楚对方是谁，才能做任何有用的事。

**通常由以下部件组装而成：**
- 一个驻守在该渠道的智能体
- 一项核实发送者真实身份的技能
- 一项查找匹配记录的技能，并在找不到匹配时提供合理的兜底方案
- 平台自带的文档接收功能，用于处理以文件形式发来的内容
- 一项对传入的自由文本进行筛查、识别其中不应自动执行的内容的技能
- 一项请人做出决定的技能
- 一项签发一次性访问链接的技能
- 一项发送消息的技能
- 一项保存记录的技能

## 5. 多智能体审查团

**它是什么样子：** 一个案例需要依据规则手册进行判定，而这个判定确实需要不止一种视角——由一名主导者统筹协调多位专才。

**通常由以下部件组装而成：**
- 一个主导智能体、一个或多个专才评估智能体、一个规则手册读取器，以及一个报告撰写器
- 一项查询底层记录的技能
- 一项按规则核对数值的技能
- 一项将引用的条目与其来源进行核对的技能
- 一项比对记录的技能
- 一项执行计算的技能
- 一项保存结果记录的技能
- 一项请人做出决定的技能
- 一轮针对整个案例的独立审计

## 6. 自动建档型 CRM

**它是什么样子：** 笔记、通话记录和消息不断涌入，需要转化为记录，再由人确认，而不是靠人手动录入。

**通常由以下部件组装而成：**
- 一个读取传入笔记和消息的智能体
- 一项把传入文档拆分成各个独立部分的技能
- 一项核实引用条目的技能
- 一项保存记录的技能，包括保存归属于它们的任何嵌套子记录
- 一项持续记录变更内容和时间的技能
- 一项在任何内容被视为最终结果之前请人确认的技能
- 一项撰写简短报告的技能
- 一项撰写并发送邮件的技能
- 一项自动化，会等待一连串相关活动告一段落后再采取行动，而不是在第一项一出现就立刻触发、结果其余项目一到就出错

## 7. 合同或文档管理

**它是什么样子：** 一份长文档——合同、协议、长篇备案文件——驱动出一条工作记录，以及一份围绕它需要发生的事项排期表。

**通常由以下部件组装而成：**
- 一个（有时是两个协同工作的）读取文档的智能体
- 一项拆分文档并将其路由到正确处理流程的技能
- 一项提取大量字段、并将结果与完整字段清单核对的技能
- 一项核实引用条目的技能
- 一项按规则核对数值的技能
- 一项填写模板的技能
- 一项签发一次性访问链接的技能
- 一项存储结果文件的技能
- 一项按固定节奏运行整个周期的定时自动化

## 8. 知识套件

**它是什么样子：** 人们就一批文档——政策、手册、过往来往信函——提出问题。

这是唯一一种最直觉的做法往往是错误做法的形态，因此值得把它拆成两类来看：

- **“我该怎么做”**这类是真正的搜索问题。平台自带的、针对一批文档的内置检索功能就能很好地处理，不需要在上面再搭建任何东西。
- **“有多少个”**或**“哪份文档在第几页提到了这一点”**这类是计数和引证问题，最好由记录来回答，而不是靠检索。把每一页都索引为一条独立记录，再用一项查询这些记录的技能和一项对其分组汇总的技能。这样一来，计数和引证就能做到精确无误。

## 9. 治理能力展示

**它是什么样子：** 这类构建的重点在于展示谁可以看到什么——访问权限、脱敏和审计——而不是任何一笔具体的交易。

**通常由以下部件组装而成：**
- 平台自带的访问管理、视图级脱敏、模型治理和读取审计
- 一项对智能体输出内容中的敏感字段进行脱敏的技能
- 一项筛查文本的技能
- 一项签发一次性访问链接的技能
- 一项对智能体自身答案进行的输出核查，作为平台视图级脱敏之外的第二道防线

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/human-approval.md ====================

---
title: 人工批准
description: 一个人如何在自己本来工作的地方做出决定——一封带有“批准”和“拒绝”按钮的邮件，再到页面上确认——以及构建在这之后如何接着把事情做完。
level: '3'
track:
- build
verified_on: '2026-09-30'
---

# 人工批准

每一个重要的构建，都有这样一个时刻：必须有人点头，某样东西才能发出去。请先设计这个时刻：要请谁决定、他们本来在哪里工作、眼前有哪份文档、他们看到什么，以及他们答复之后会发生什么。

## 决定是一回事，做出决定的场合是另一回事

决定这部分的工作，是从底层记录中算出应当发生什么，如果还没有人做出决定就拒绝继续，并记下是谁决定的、决定了什么、什么时候决定的。这部分不会因构建而改变。

而做出决定的场合——一个人具体在哪里、以什么方式做出这个决定——按用例来选，但默认做法并不是可以随意挑的：一个人在自己本来工作的地方做决定。对大多数审核人来说，那就是他们的收件箱。

## 默认做法：带有“批准”和“拒绝”的邮件

审核人会收到一封邮件，里面有做决定所需的一切：相关事实、文档本身（报价单、简历、合同）的链接或附件，以及建议的处理方式。下方是两个按钮，“批准”和“拒绝”。

1. 构建暂停下来，并给审核人发邮件。等待期间，不会有任何东西发出去。
2. 审核人阅读这封邮件，文档就在眼前。
3. 点击其中一个按钮，会打开一个确认页面，显示他们所选的结果。仅仅打开页面，不会决定任何事。
4. 只有在页面上点击“确认”，才会记录这个决定。另一个按钮随后就会失效，所以一个人只会给出一个答案。
5. 同一次运行接着往下走：完成工作——例如把文档发给销售人员——并告诉提出请求的人发生了什么。

在构建任何东西之前，先用五行字写下这个时刻：要请谁决定、他们本来在哪里工作、眼前有哪份文档、他们看到什么，以及他们答复之后会发生什么。然后记住三件事。

- **以人、消息和文档为主。** 这个时刻是一个人、一封邮件和那份文档，而不是一张表格。数据表只是它背后的记录。
- **邮件是一张卡片，而不是一条通知。** 如果审核人得另外打开别的东西才能做决定，就说明这张卡片缺了一项事实。
- **每一条分支，都要结束在提出请求的人看得到的地方：** 已批准、已拒绝、已过期、无人答复。

## 其他方式，以及何时使用

| 场合 | 运作方式 | 适用场景 |
|---|---|---|
| **带确认页面的邮件** | 每种结果各一个按钮；点开按钮会显示一个页面，在上面确认才会写入决定 | 默认做法，适用于每一位在收件箱里工作的审核人 |
| **记录上的一个字段** | 一个人在数据表上切换状态字段；保存之后，下一步就会触发 | 备用做法，只在审核人本来就每天在这张数据表上工作时才用。不适合一般业务人员 |

不要要求业务人员通过在数据表里选一个值来批准。那个值藏在一张他们没有理由打开的表格里，要保存后才会生效，也让人感觉不像是在做决定。

具体有哪些场合可用，取决于你的安装环境和版本；你的 iMBrace 联系人可以为你确认。无论选择哪一种，在依赖它之前，都要亲自以审核人的身份走一遍：他们收到邮件、打开、确认，然后构建把事情做完。

## 不能变通的规则

**在聊天里友好地打一声“好”，本身并不算是一项决定。** 那只是流程控制——它可能只是让对话继续下去——但它不会留下任何持久的记录，让日后有人能够指出：这件事在这个时间，由这个人批准。决定是一条绑定到具体某一项的记录，记下了是谁在什么时候做出的决定。

还有两条值得牢记的规则：

- **关卡自己算出答案。** 它会根据底层记录重新计算结果，而不是相信同一次互动中刚被告知的数字。一个只相信别人告诉它什么的关卡，会很乐意批准一个错误的数字。
- **没有决定，就没有输出。** 不是默认放行，也不是过一段时间超时就自动放行。只要还没有人做出决定，就不会有任何东西发出去。

## 让关卡真正守住的细节

- **打开链接，不会决定任何事。** 人、邮件扫描程序或预览功能都可能打开它。访问只会显示页面；只有确认这一步才会做出决定。
- **每个人一封邮件、一组按钮。** 在你自己的记录上，记下这组按钮属于谁、他们何时确认，这样“由谁批准”永远来自你自己的记录。
- **第二个答案不会改变任何事。** 一旦有一个答案被确认，另一个结果就会失效，而且暂停之后的那一步，重复运行也是安全的。
- **确认页面如实呈现。** 只有在决定确实被记录下来之后，才显示“完成”；如果没有记录成功，就明确说出来。
- **等构建真的在等待答案时，才发出邮件。**
- **智能体绝不能有写入决定的能力。** 用来记录决定的列，应当在记录创建时就取好起始值，并拒绝智能体之后对它的任何写入——只给智能体范围狭窄、碰不到这些列的工具。
- **“还没有结论”绝不能被当成“通过”。** 一项还没运行、或已经失败的检查，会让记录看起来和真正通过的一模一样。请在每一条记录上都打上结论，包括没问题的那些，并让此后每一步都等待这个结论、没有它就拒绝继续。
- **数据表里的编辑，要到点击“保存”（Save）之后才会生效。** 如果审核人确实使用数据表，请从已保存的状态测试这个关卡，并在给他们的操作说明里加上“点击‘保存’”这一步。

## 证明关卡确实接上了线路，而不只是摆在那里

一个控制点的好坏，取决于它究竟绑定了什么。把这个场合接到真正依赖它的东西上，并以审核人的身份，把整条路径端到端实际走一遍：对每一种结果——批准、拒绝、无人答复——都启动一次运行，从他们实际会收到的那封邮件答复，然后确认工作已完成，或提出请求的人已被告知，而且不需要任何人再提示。在这件事做完之前，关卡都不算建好。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/native-first.md ====================

---
title: 原生优先
description: 为什么要先动用平台自身的构建部件、再考虑写代码，以及这样做能带来什么好处。
level: '3'
track:
- build
verified_on: '2026-09-23'
---

# 原生优先

在写自定义代码去做某件事之前，先确认平台是不是已经能做到这件事。这不是风格上的偏好选择。它会直接影响你的构建运行起来要花多少成本、能不能安全地迁移，以及日后别人理解它有多容易。

## 一句话讲清这个道理

如果一个人能够指着某项能力、把它说成平台的一项功能，那么这项能力几乎肯定已经内置在平台里了。你自己用自定义代码把它重新做一遍，会把它的实际作用藏到一段别人必须去读的代码背后，还往往会随着平台演进而逐渐落伍过时，而且很多时候最终还需要一个内置方式原本根本用不到的登录凭证。

## 平台开箱即用通常已经提供了什么

这一类可正常运行的平台，出厂就自带大量现成的能力：读写结构化记录、通过常用渠道发送邮件和聊天消息、日历、电子表格、文件存储、处理传入的文档、暂停一个流程以等待人来处理、从一个流程调用另一个流程、在流程内部做路由和循环，以及干净地终止一次运行。与各类账户和其他系统的连接，都保存在平台自身的连接存储中——配置一次，由构建引用，绝不会被带进构建自己的逻辑里。

在写下第一行自定义代码之前，值得先查一查平台当前的能力清单，看看有没有现成的东西已经能完成这项工作。新的能力会不断持续上线，最安全的默认做法永远是先查看、再动手构建。

## 什么时候自定义代码才真正站得住脚

以下两件事必须同时成立：

1. **没有任何内置能力能完成这项工作**，而且你能具体说出自己查过什么、为什么那些都不够用。
2. **这段代码是纯粹的**——它只对拿到手的值进行计算，本身不会带着自己的凭证去调用另一个系统。如果它确实需要触达另一个系统，也要通过平台自身的某个连接去做，而不是靠代码里嵌的一个密钥。

任何偏离原生优先原则的例外情况，都应该被明明白白地记录下来：考虑过什么、为什么没有采用，以及将来要满足什么条件才能让这段自定义代码退役。把这种例外当作一项临时的、有名有姓的债务来对待，而不是一个悄悄变成永久的选择——一旦平台上线了能做同样工作的内置方式，就立刻让它退役。

## 为什么这件事比听起来更重要

- **构建里的任何东西都不应该保存凭证。** 一个只使用平台自身连接的构建，不包含任何登录信息、任何 API 密钥，任何这类东西都没有。这意味着这个构建本身可以被安全地分享、导出，或者迁移到另一个账户——里面没有任何东西需要被轮换、被脱敏或者让人担心。
- **一个使用内置能力构建出来的东西，非开发人员也能读懂。** 他们可以打开它，一步一步地看到每个部分在做什么，根本不需要打开任何代码。自定义代码则会把这一切藏到一堵只有开发人员才能读懂的墙后面。
- **它经得起迁移。** 把一个完全用内置能力构建出来的东西导出到另一个账户，不需要任何重新接线。一个把凭证写死在里面的构建则会失效——更糟的情况是，它悄悄地继续运行，用的却是错误账户的权限。像 Gmail 这样使用服务商登录的连接，由有权限的人在每个账户上完成一次授权即可；邮件服务器（SMTP）连接则是用服务器信息配置一次即可。

## 好的样子是什么

- 这个构建在平台自身的视图里，能够一步步读下去，不需要打开任何代码就能看懂。
- 在构建的逻辑里搜索任何凭证类的东西，结果什么都搜不到。
- 如果有自定义代码，每一段都附有一条说明，写明考虑过哪项内置能力、为什么它不够用。
- 把这个构建迁移到另一个账户，不会改变它的任何行为。

## 一个实际例子

以一个报价助手为例：发送完成后的文档完全不需要任何自定义代码——读取记录、按状态路由、格式化日期、发送邮件、更新记录，这些步骤全部都是内置的。审批环节的做法也是一样，用一个内置任务暂停流程、等人做出决定，然后自己接着往下走，把文档发出去。自定义代码通常只局限于少数几件事：算术运算、一次数据库查询、一次最终核查，以及文档本身的排版。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/document-models.md ====================

---
title: 文档模型
description: 如何选择让文档模块（DocIQ）从文档中提取什么内容——优先采用平台的默认模型，其次扩展它，只有在万不得已时才自己编写。
level: '3'
track:
- build
verified_on: '2026-09-23'
---

# 文档模型——采用、扩展、自己编写

当“文档模块”（DocIQ）读取一份文档——一份简历、一张发票、一张采购订单——**文档模型**会告诉它要提取什么内容、填到哪条记录里。获得一个文档模型有三种方式，而且有严格的先后顺序。

1. **采用组织的默认模型。** 平台自带一个庞大的模型库，涵盖简历、发票、采购订单和入职核对清单等。采用一个默认模型不花任何成本，并且这个组织今后的每一次构建，看到的都是同一套字段。
2. **当某个字段确实缺失时，扩展一个默认模型。** 联系你的 iMBrace 联系人。把一个字段加进默认模型，会让它出现在每一个组织面前，而不是为单个客户单独拉出一个分支模型。
3. **只有在不存在默认模型的地方，才自己编写**，并且要用平台自身的风格来写，这样将来的默认模型才能干净利落地取代它。

## 不要做的事

- **把模型管理当作一个独立、刻意的步骤来做，绝不要把它当成某次构建的副产品。** 在正在运行的构建之外创建或修改文档模型，这样每一个读取某类文档的构建，指向的都是同一个、唯一的模型。
- **不要把模型的选择交给运气。** 如果某一步总是读取同一类文档，就明确告诉它该用哪个模型，这样每一份文档都会落在你预期的那张数据表上。

## 用自己的文档来验证

在一项设计开始依赖它之前，先用几份你自己的文档，逐一核查以下每一点：

- **一个字段很多的模型。** 一个有几十个字段的模型，拆成几轮各有侧重的核查，会更容易验证。不管模型大小，都要把每一次结果对照字段清单逐一核查，确保每个字段都有着落。
- **嵌套行。** 发票上的明细行、简历工作经历里的各段任职：在你的测试集里确认，每一条子行都落在与其父记录相链接的那张数据表上。
- **一份其实是表格的文档**——比如一份价目表、一份对账单——它对应的是许多条记录，而不是一条。要把它当作若干行来读取。
- **一份看起来不像自己类型的文档。** 在测试集里加入一些不典型的样本——比如一份没有职责部分的职位描述、一份缺少标准标题的表单——并确保智能体会把无法识别的文档如实报告为“无法识别”，而绝不会谎报成功。
- **面向整个组织的设置。** 文档模块的模型设置是在整个组织范围内共享的。把你的构建测试时所用的设置，记录在你的测试集旁边，并且每当设置发生变化，就重新跑一遍测试集。
- **模型运行在哪里。** 由哪个模型来读取你的文档，是按安装环境、按组织分别设置的。如果个人数据必须留在本地，就要请负责这套安装的人确认：文档模块所用的每一个模型——无论用于阅读还是用于检索——都运行在这套部署内部，然后才能放入第一份真实文档。

## 值得投入的设计选择

- **模型越少，越省成本、也越准确。** 分类时，会把每一份文档与组织里的每一个模型逐一比对，所以每一个用不上的模型，都会增加成本和出错的空间。只保留你在用的模型；如果某一步总是读取同一类文档，就让它指向那类文档对应的数据表，把模型固定下来。
- **对任何你会用来分组或制图的字段，给它一个封闭的词表。** 在字段的说明里列出所有允许的取值，这样分组和制图，用的就是一套固定、已知的术语。
- **用一份文档是什么、又不是什么，来描述每一种文档类型。** 说明里点出那些和它极为相似、但并不是它的类型，正是让不同类型彼此区分开的关键。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/anti-patterns.md ====================

---
title: 反模式
description: 一再被构建出来的错误、每一种的代价，以及对应的修复方法。
level: '3'
track:
- build
verified_on: '2026-09-30'
---

# 反模式

这些做法在当下往往显得合理，这正是为什么值得提前把它们一一点名。

## 背后空无一物的关卡

一个本该由人更新的状态字段，实际上却没有任何东西在监看它，也没有任何东西依据它的变化采取行动。**代价：** 它在评审时看起来像是有监督，但到了生产环境里却什么监督也没有——东西发出去了，却没有人真正批准过。**修复方法：** 把这个界面接到真正依赖它的东西上，并在正式宣布完成之前端到端走通整条路径，包括“还没有人做决定”这种情况在内。

## 填在单元格里的决定

一个人被要求在数据表里编辑一个值来批准。**代价：** 那个值藏在一张他们没有理由打开的表格里，要保存后才会生效，没有一个业务人员会把它当成在做决定——于是批准来得很晚，或者根本不来。**修复方法：** 在他们本来工作的地方请他们决定：一封卡片式的邮件，按钮会打开确认页面，文档就在眼前，之后再把决定记录到那一行上。参见[人工批准](human-approval.md)。

## 问完就挂起的请求

一个构建向人请求做决定，然后就停在那里。决定本身被记录下来了，但后续什么都没有发生：文档没有被发出去，提出请求的人也没有被告知，只能靠自己发现问题、再回来重新问一次。**代价：** 它能通过评审，却在生产环境里失效——工作被记录下来却没有完成，还得有人手动去追。**修复方法：** 设计这个请求环节，使其在得到答复后（无论是批准、驳回，还是被搁置）能够自动接着往下走，让流程自己把工作做完，或者自己报告结果。

## 自信满满的总结

一个由 AI 生成、读起来很顺、但背后什么依据都没有的答案。**代价：** 正因为它读起来令人信服，才能在评审中蒙混过关，结果决策就建立在一个谁也无法追溯的数字上。**修复方法：** 要求每一个数字都必须带上它的出处记录；当数据中确实没有答案时，就直接说明，而不是自己编一个来填补空白。

## 可以绕过的计算器

没有任何机制强制让运算经过一个专门的、可核查的步骤，于是在压力之下，AI 就自己把数算出来了。**代价：** 它通常是对的，而这恰恰是危险所在——出错的情况很少见、也很安静，不到有人去核查往往不会被发现。**修复方法：** 每一次都把所有运算路由到同一个专门的计算步骤，并展示所用的输入。

## 写进提示词里的规则手册

把限额、标准或阈值直接写进 AI 的指令里，而不是作为可编辑的数据来保存。**代价：** 业务人员没有开发人员协助就没法改动一个数字，也没有人能审计某个案例究竟触发了哪一条规则。**修复方法：** 把规则作为数据保存在一条记录上，让非开发人员也能直接打开并编辑。

## 分叉出来的副本

复制一个正常运行的构建的内部逻辑，为新的场景做出一个几乎一模一样的版本，而不是把原来的构建参数化。**代价：** 变成两样东西要维护，还会在不知不觉中彼此走样，而且下一个接手的人往往根本不知道还存在第二份副本。**修复方法：** 用参数化代替复制。如果确实需要一个真正独立的第二版本，就给它自己的名字和自己的文档，而不是让它冒充原来那一个。

## 自建捷径

用自定义代码去做平台本来就已经内置提供的事情，通常是因为事先没有人去核实过。**代价：** 它通常需要一个原本内置方式根本不需要的凭证，而且构建一旦迁移到另一个账户就会失效。**修复方法：** 在写任何代码之前，先查一查平台当前的能力清单。参见[原生优先](native-first.md)。

## 未经核查的提取

不经核对就直接信任一次提取的结果，而不去对照当初要求提取的内容。**代价：** 如果没有人拿输出结果去对照字段清单，漏掉的字段很容易被忽略。**修复方法：** 把每一次提取结果都对照字段清单逐一核查，并把过长的字段清单拆成几轮各有侧重的提取。

## 用检索来数数

把计数或引证类问题——“有多少个”“哪份文档在第几页提到”——当成搜索问题来处理。**代价：** 这类问题需要结构化记录才能给出精确答案；单靠检索没法展示它的推导过程。**修复方法：** 把材料索引成结构化记录，再对其进行查询。把搜索检索留给真正的“我该怎么做”这类问题。

## 抢跑触发

一个流程对一连串相关活动中的第一项就立刻做出反应，而不是等这一连串活动告一段落。**代价：** 结果在其余相关项目到达之前就已经生成，一旦其余项目到达，它当场就变得错误或不完整。**修复方法：** 等这一连串活动平静下来之后，再针对完整情况一次性采取行动。

## 轻信的关卡

一个审批环节直接读取 AI 刚刚给出的数字，而不是根据底层记录独立算一遍。**代价：** 一个错误的数字可以自己批准自己，因为从来没有人拿它去对照过原始来源核实。**修复方法：** 这个关卡必须每次都自己重新推导出答案。

## 自我汇报

一个构建自己汇报自己的成功——一段看起来煞有介事的粘贴结果，一个“已完成”或“已上线”的状态，而实际上从来没有人真正看着它运行过。**代价：** 对一个从未被真正观察到的世界状态抱有信心。**修复方法：** 亲自运行一遍，亲眼看着它发生，只有在真正有人看到它成功运行之后，才能把它标记为可用。

## 绕开隐私保护的捷径

为了回答一个棘手的问题，临时把一处存放原始敏感数据的存储直接连接给 AI。**代价：** 敏感数据与 AI 之间的隔离，本来就是整个隐私保障的全部内容，而这一刻，它已经在悄无声息中不再成立了——哪怕只是短短一瞬间。**修复方法：** 绝不连接，哪怕只是暂时的也不行。如果一个问题确实需要用到原始数据，那这个问题本就不该由那个 AI 来回答。

## 写进提示词里的标准答案

把预期答案——也就是演示应该展示出来的那些数字——直接写进智能体自己的指令里。**代价：** 演示能通过，但背后的工具其实是错的，而且要等到真正有人提出问题时才会被发现。**修复方法：** 预期数值只应存在于测试集中，绝不能出现在指令里；在智能体上线之前进行一次检查，一旦指令中包含这些数值就予以拒绝。

## 把记忆当成数据来源

一个智能体靠自己记得的内容、或者靠此前某个时间点附加给它的文档来回答一个实时数据问题，而不是去读取眼前的原始来源。**代价：** 一个语气自信、却装着过时数字的答案。**修复方法：** 不要给任何依据实时数据作答的智能体附加文档，给它定一条常设规则——绝不把数字存进记忆，也绝不凭记忆作答，并且保留一道能够识破过时答案的测试问题。对于任何需要维持一段对话的智能体，要保留它自己的对话历史——它需要靠这段历史，才能对自己先前说过的话保持一致。

## 在有争议的数字上让步

某个人提出自己的一个数字，智能体就放弃了自己原本用工具算出来的正确数字，转而附和对方。**代价：** 答案变成了对话中语气最自信的那个人说了算。**修复方法：** 给智能体定一条质询规则——重新跑一遍工具、尝试用工具复现对方给出的数字，并清楚说明每个数字各自代表什么。

## 透视表快照

把一份转换过格式的表格里的数据透视表当成仍在实时计算来读取。当一个 Excel 工作簿被转换成 Google 表格时，其中的数据透视表会保留转换那一刻显示的数值，之后就不再更新。**代价：** 从透视表里取出的每一个数字，都被冻结在转换发生的那一天，无论底下的原始行数据有多新。**修复方法：** 从原始行数据重新计算，并且无论在哪里展示这份透视表，都要注明这一点。

## 整张表甩进一轮对话

在一轮对话里，把一整张大型表格或数据表原封不动地丢给智能体。**代价：** 这超出了智能体一次能消化的量，之后的一切都建立在一次看似完整、实则只读了一部分的基础上。**修复方法：** 用平台自带的读取步骤来读取它，用一个计算步骤汇总它，只把算好的最终数字交给智能体，并附上这些数字所依据的行、筛选条件和日期。参见[原生优先](native-first.md)。

## 从未被复用的共享部件

因为看起来“应该会有用”而构建出来的东西，实际上却从来没有被真正复用过，却还要一直维护下去。**代价：** 持续投入维护成本却换不回任何价值，还会让人误以为这个构建比实际情况更模块化。**修复方法：** 在至少有两个真实、独立、且叫得出名字的需求出现之前，不要把某样东西标注为“可复用”。

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*


==================== build-it-well/review-checklist.md ====================

---
title: 审查清单
description: 八项原则审查，做成一份清单，供你在交付前对照自己的构建逐项核查。
level: '3'
track:
- build
verified_on: '2026-09-30'
---

# 审查清单

这就是内部一直在用的那套审查，这里把它写成你可以自己拿来对自己的构建使用的版本。完成一次大约需要一个小时；如果执行审查的人，不是这个构建的开发者，效果会好得多。

## 如何进行这项审查

1. 把下面的评分表复制一份，放在你正在审查的构建旁边。
2. 逐条过一遍每项原则下的问题，这些问题取自[八项原则](the-eight-principles.md)。
3. 为每个问题打分：**已达成**、**部分达成**、**未达成**，或**不适用**。
4. 每个分数都需要一个**依据**——某样具体的东西来证明它：一条具体的记录、一段你亲眼看到发生并粘贴下来的结果、一张实际行为的截图。一个背后什么都没有的分数，只是一个人的看法，算不上审查。
5. 任何被打上**未达成**的项，要么在交付前修复，要么写一条带日期的书面说明，说明是谁接受了这个差距、为什么接受。

## 让这项审查真正值得做的几条规则

- **评审人不是这个构建的开发者。** 一个人审查自己的作品，往往只能发现自己本来就已经知道的问题。
- **动手运行，不要只是看着推测。** 不要因为一项测试看起来应该会通过，就认定它通过了。把它运行一遍，亲眼看着结果。
- **“不适用”需要一个理由。** 这是一个正当的分数，但沉默不是——写清楚这个问题为什么在这里不适用。
- **部分达成不等于通过。** 它是一个被明确指出的差距，要有负责人，最好还要有一个重新审视它的日期。
- **这审查的是构建，不是人。** 目标是得到一个更好的成果，而不是对做出它的人下判断。

## 1. 可溯源性（Provenance）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 不借助他人帮助，你能否从输出里的一个数字，一路找到它背后的那条记录？ | | | |
| 2 | 这个答案是否带有一个截至日期？ | | | |
| 3 | 一句被引用的内容，是否能对照其出处得到证实，并给出具体位置？ | | | |
| 4 | 当数据无法回答这个问题时，一个人会看到什么？ | | | |
| 5 | 每一句被引用的内容，是否真正支持它所对应的结论，还是只是恰好出现在源材料里？ | | | |

## 2. 确定性（Determinism）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 每一个数字，具体是在哪里算出来的？ | | | |
| 2 | 一个业务人员能否在不找开发者的情况下，自行修改一个阈值？ | | | |
| 3 | 同一个问题问两次，得到的答案是否一样？ | | | |
| 4 | 当系统遇到一条它尚未实现的规则时，会发生什么？ | | | |

## 3. 模块化（Modularity）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 对任何被标记为“共享”的东西，说出两个真实存在、彼此独立的使用场景。 | | | |
| 2 | 是否存在这样的变体：它们之间的差异其实来自一次修改，而不是来自配置？ | | | |
| 3 | 一个部件能否脱离实际账号和网络，独立完成测试？ | | | |
| 4 | 这个构建里，是否存在没有真实、具名用户的部分？ | | | |

## 4. 无领域内核（Domain-free cores）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 核心逻辑里，是否出现了公司名称或某个客户特有的细节？ | | | |
| 2 | 只靠修改配置，这个核心能否服务于另一家公司？ | | | |
| 3 | 配置里的每一项设置是否都被用到了，而每一个被用到的东西是否都在配置里声明过？ | | | |
| 4 | 是否有任何工作流程里，包含了某台机器的网络地址？ | | | |

## 5. 人的治理（Human governance）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 展示最近一次决定的记录。谁决定的？决定了什么？什么时候决定的？ | | | |
| 2 | 如果审核人联系不上，还会有东西被发出去吗？ | | | |
| 3 | 这个关卡是自己算出答案，还是相信别人递给它的答案？ | | | |
| 4 | 审核人本来在哪里工作？那条路径是否曾以他们的身份端到端走通过？仅仅打开链接，会不会决定任何事？ | | | |
| 5 | 当同一个决定送达两次时，会发生什么？ | | | |
| 6 | 智能体能否写入用来记录决定的那些列？ | | | |
| 7 | 当一项检查还没有在记录上打下结论时，后面的步骤会怎么做？ | | | |
| 8 | 批准一项、拒绝一项、再留一项不做处理。每一次，流程是否都能自行继续往下走？ | | | |

## 6. 原生优先（Native-first）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 一个不是开发者的人，能否读懂这个构建，并说出每一步在做什么？ | | | |
| 2 | 在构建里搜索，是否会找到任何看起来像凭证的东西？ | | | |
| 3 | 对每一段自定义代码，是否考虑过、又放弃了哪个内置能力？为什么？ | | | |
| 4 | 把这个构建搬到另一个账号下。什么会坏掉？ | | | |

## 7. 可运维性（Operability）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 你是否亲自运行过这些测试，并亲眼看着它们通过？ | | | |
| 2 | 固定测试集在哪里，它上一次评分是什么时候？ | | | |
| 3 | 重置是否能把这个构建，恢复到完全相同的起始状态？ | | | |
| 4 | 有什么在独立核查这条主路径，它上一次与主路径的结果不一致是什么时候？ | | | |
| 5 | 一个素不相识的人，仅凭这个安装包和文档，能否把它装起来并运行？ | | | |
| 6 | 对每一步，哪条记录能证明这项工作确实发生过？ | | | |

## 8. 安全与主权（Security and sovereignty）

| # | 问题 | 分数 | 依据 | 备注 |
|---|---|---|---|---|
| 1 | 即将被分享出去的东西里，是否包含任何看起来像凭证的内容？ | | | |
| 2 | 任何 AI 工具能访问到的凭证，是否都是权限有限、可随时作废的？ | | | |
| 3 | 敏感字段的脱敏，是由平台强制执行的，还是由一个可能被跳过的步骤来做的？ | | | |
| 4 | 谁能看到未经脱敏的原始数据，又是什么在真正阻止 AI 被接入这些数据？ | | | |
| 5 | 你上一次分享出去的安装包，实际包含了什么？ | | | |
| 6 | 有哪些 AI 模型会读取这个构建的数据，其中是否有任何一个在部署范围之外？ | | | |

## 已接受的差距

| 差距 | 为什么目前可以接受 | 接受人 | 日期 | 何时重新审视 |
|---|---|---|---|---|
| | | | | |

---

*版本 1.0.3，于 2026年10月4日。社区版，发布于 engineer.imbrace.co，这是一份用 AI 编程工具在 iMBrace 上构建的方法指南。*
