# iMBrace 学习，每一页合并在单个文件中 ==================== index.md ==================== --- level: '0' track: - sell - build - deploy --- # 关于本课程 这门课程带你认识 iMBrace：理解它、看它运行、在上面开发，并把它做好，提供英文、繁体中文和简体中文。它与 SDK 文档并行：文档是参考资料，课程则是带着截图、一步一步走过这些内容的导览路线。请在下方挑选适合你的路径。 ## 下载 - [AI 编程工具的构建指南（.zip）](https://engineer.imbrace.co/learn/imbrace-build-guide-community.zip) - [整门课程，给 AI 工具读取（llms-full.txt）](https://engineer.imbrace.co/zh-cn/learn/llms-full.txt) 合作伙伴套件（演示脚本、交付与部署指南、一个练习用组织）不提供下载，请向你的 iMBrace 联系人索取。 ## 挑选你的路径 - [向客户介绍 iMBrace](/zh-cn/learn/understand/overview.md) - 它是什么、今天能做什么，以及实际运行的平台导览。 - [在 iMBrace 上开发](/zh-cn/learn/build-it/set-up-your-coding-tool.md) - 设置你的编程工具，然后构建一个能运行的小型退货台，并让它等待人的决定。 - [使用 AI 编程工具开发](/zh-cn/learn/build-guide.md) - 把构建指南交给你的工具，或提供整门课程合并成的单个文件。 - **成为 iMBrace 合作伙伴** - 合作伙伴套件内含演示脚本、交付与部署指南，以及一个练习用组织。 ### 每条路径上的所有页面，按顺序排列 **向客户介绍 iMBrace。** [什么是 iMBrace](/zh-cn/learn/understand/overview.md)，接着 [iMBrace 今天能做什么](/zh-cn/learn/understand/capability-truth-table.md)，接着 [平台导览](/zh-cn/learn/see-it-work/platform-tour.md)，接着 [简历筛选，从头到尾](/zh-cn/learn/see-it-work/cv-screening.md)或 [销售报价](/zh-cn/learn/see-it-work/sales-quoting.md)。 **在 iMBrace 上开发。** [设置你的编程工具](/zh-cn/learn/build-it/set-up-your-coding-tool.md)，接着 [构建模块](/zh-cn/learn/build-it/building-blocks.md)，接着 [教程](/zh-cn/learn/build-it/vibe-coding-tutorial.md)，接着 [让它等待人的决定](/zh-cn/learn/build-it/make-it-wait-for-a-person.md)，接着 [与 AI 编程工具协作](/zh-cn/learn/build-it/working-with-ai.md)，接着 [构建得好](/zh-cn/learn/build-it-well/index.md)。动手实践的教程约需一小时；“让它等待人的决定”是第二次动手。 **使用 AI 编程工具开发。** 从 [AI 工具的构建指南](/zh-cn/learn/build-guide.md)开始。你的工具也可以读取 [整门课程合并成的单个文件](https://engineer.imbrace.co/zh-cn/learn/llms-full.txt)。 **成为 iMBrace 合作伙伴。** 合作伙伴套件另附演示脚本、交付与部署指南，以及一个练习用组织。请向你的 iMBrace 联系人索取。 ==================== understand/overview.md ==================== --- 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 今天能做什么](/zh-cn/learn/understand/capability-truth-table.md) 会逐个领域给出详细说明，并附上页面或界面，方便你亲自查看每一项能力。 ==================== understand/capability-truth-table.md ==================== --- 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 | ==================== see-it-work/platform-tour.md ==================== --- level: '1' track: - sell - build - deploy verified_on: 2026-09-29 --- # 平台导览 这是 iMBrace 组织的侧边栏，按它排列的顺序逐一走一遍：应用、分析模块（InsightsIQ）、知识模块、 行动模块、治理管控模块和设置。每个区域只停留一小段——它是做什么用的、打开后能看到什么，以及 在那里最值得给客户看什么。第一次做演示前先读一遍，之后把它当成清单打开，带别人走一遍平台时 随时对照。 ## 应用 应用是与客户或员工的对话真正发生的地方。它打开后停在“对话”（Conversations），这是一个共享 收件箱，汇总来自所有已连接渠道的每一条消息，并带有按视图和按状态筛选的标签——在线、逾期、 需要客服、待处理、已关闭。无论消息从哪个渠道进来，都汇总成同一份列表。可以给客户展示一条对话 实时进来的样子，也可以筛选到“逾期”，展示没有任何一条被漏答。 画面：应用侧边栏，显示对话收件箱与其状态筛选 *1 “应用”（Applications）>“对话”（Conversations）。2 共享收件箱的“状态”筛选。* ## 分析模块 “分析模块”（InsightsIQ）是你直接和智能体对话、看它如何处理一个问题的地方。它打开后停在一个 对话界面：用来选择你要问哪个智能体的选择器，以及用来提问的输入框。输入一个真实的问题，展示 答案是如何出现的——它背后是该组织自己批准的知识，如果答案不在其中，也会明确说明。实际效果见： [简历筛选全流程](/zh-cn/learn/see-it-work/cv-screening.md)和[销售报价](/zh-cn/learn/see-it-work/sales-quoting.md)。 画面：分析模块的聊天页面，含智能体选择器与输入框 *1 “分析模块”（InsightsIQ）。2 智能体选择器。* ## 知识模块 “知识模块”（Knowledge）保存着该组织所掌握的一切：读取其文档的模型、保存其结构化记录的数据表， 以及智能体据以作答的资料。 ## 文档模块 “文档模块”（DocIQ）是文档模型把一份非结构化文件——一张发票、一份表单、一份简历——变成一条 结构化记录的地方。它打开后停在“文档模型”（Document Models），这是一个已经按类别整理好的库， 类别包括财务与会计、人力资源、销售与客户，旁边还有文档表和处理日志。打开一个已经和客户自己的 单据相匹配的模型，展示它逐个字段提取出的内容。 画面：文档模块的文档模型标签页，含分类条 *1 “知识模块”（Knowledge）>“文档模块”（DocIQ）。2 一张文档模型卡片。* ## 数据表 “数据表”（DataIQ）是结构化记录真正存放的地方：一张数据表，由你自己定义的行和有类型的列组成。 它打开后是一张张数据表卡片，每张卡片显示数据表的名称和它保存的记录数。打开一张数据表，直接从 表里读一行真实数据——工作流程的步骤、智能体的技能，以及文档模型的提取结果，读写的都是同一张表。 画面：数据表卡片列表，显示各数据表的记录条数 *1 “知识模块”（Knowledge）>“数据表”（DataIQ）。2 一张数据表卡片。* “文档模块”（DocIQ）的文档模型和“数据表”（DataIQ）的数据表，是每一个 iMBrace 构建都由其搭建而成 的[五个基本部件](/zh-cn/learn/build-it/building-blocks.md)中的两个；接下来的“行动模块”（Actions）则包含 另外三个——智能体、工作流程和渠道。 ## 通讯模块 “通讯模块”（CommsIQ）与“文档模块”（DocIQ）和“数据表”（DataIQ）并列，有自己的“全部”标签页。 ## 知识库 “知识库”（KB）是直接上传参考资料的地方——PDF、Word、PowerPoint、Excel、CSV、视频或图片 文件——按文件夹整理，供智能体直接引用作答，不必有人重新键入。如果客户自己的资料已经上传， 就打开对应的文件夹，展示智能体的回答如何直接引用其中的内容。 ## 行动模块 “行动模块”（Actions）是另外三个基本部件所在的地方：负责对话的智能体、负责完成工作的工作流程， 以及负责来回传递信息的渠道。 ## AI智能助手 “AI智能助手”（AgentIQ）是搭建和配置智能体的地方。它打开后是三个标签页——“市场”（Marketplace）、 “我的 AI”和“启用中的 AI”——“启用中的 AI”列出每一个已经在工作的智能体，每一个都有自己的卡片：销售报价 智能体的卡片上写着“把一句大白话的请求，变成一份带价格的 Quillmoor Components 报价单”。打开某个 智能体的“行为设置”，滚动到“功能”（Skills），可以清楚看到它配置了调用哪些工作流程，每一个都是 为特定任务搭建和命名的。 画面：AI智能助手的启用中的 AI 标签页，列出组织的所有助手 *1 “行动模块”（Actions）>“AI智能助手”（AgentIQ）。2 Sales Quoting 助手的卡片。* ## 流程运营模块 “流程运营模块”（FlowOps）是搭建和查看工作流程的地方：一旦被触发，一串步骤就会自动运行——读取 数据表、进行计算、等待某个决定、发送消息。它打开后直接显示已经在运行的工作流程列表。打开其中 一个，指出它等待合适的人做决定的那一步，然后展示它一旦获得决定，就会自动继续并完成剩下的工作。 关于这个决定具体在哪里做出，详见[人工批准](/zh-cn/learn/build-it-well/human-approval.md)。 画面：流程运营模块的工作流程列表 *1 “行动模块”（Actions）>“流程运营模块”（FlowOps）。2 工作流程列表中的一行。* ## 连接模块 “连接模块”（ConnectIQ）从两个方向把平台向外连接。它的“渠道设定”（Channels）标签页列出一个人 实际联系到智能体的各种方式——一个 Web Widget（状态为已启用，并允许上传文件），以及可以添加 LINE、Facebook、Instagram、微信和 WhatsApp 的选项。它的“MCP”标签页则是 AI 编程工具用来连接、直接 查看并在某个组织上构建所需的地址和密钥——完整指南见 [engineer.imbrace.co/mcp/overview](https://engineer.imbrace.co/zh-cn/mcp/overview/)。先展示 “渠道设定”，也就是客户自己的客户已经在用的这些应用，MCP 则留给懂技术的听众看。 画面：连接模块的渠道设定标签页，列出网页小部件和各消息渠道 *1 “行动模块”（Actions）>“连接模块”（ConnectIQ）。2 “网页小部件”消息渠道。* ## 治理管控模块 “治理管控模块”（Governance）是平台自己保存的一份操作与事件记录，不需要任何人特地去要。它的落地标签页 “审计记录”（Audit Log）会为整个组织的活动加上时间戳并标明是谁做的——登录、文件上传、渠道变更、 数据表的改动——这样事后都可以核查；旁边还有“硬件指标”“Token 用量”和“对话记录（AI 追踪）”。打开 “审计记录”，展示真实的一行：改了什么、谁改的、什么时候改的。 画面：治理管控模块的审计记录标签页，含时间戳的活动记录 *1 “治理管控模块”（Governance）。2 审计记录的“类型”列。* ## 设置 做演示时，“设置”（Settings）指的就是“团队管理”（Teams）和“组织成员”（Org Members）。 “团队管理”——“所有团队”和“我的团队”——是组织访问权限、设定成员在其中角色的地方，团队管理员和 代表并列，各自只能看到自己所属的团队；“组织成员”列出构成该组织的所有人。打开“团队管理”，展示 一个人的访问权限如何对应到他实际做的工作。 画面：设置的团队管理标签页，显示所有团队与我的团队 *1 “设置”（Settings）。2 “团队管理”（Teams）标签页。* 以上就是这条贯穿侧边栏的引导路径——和客户一起打开一次，每个区域都已经准备好可以展示的内容。 ==================== see-it-work/cv-screening.md ==================== --- level: '1' track: - sell - build - deploy verified_on: 2026-09-29 --- # 简历筛选，从头到尾 Lumenvale Software 的招聘人员手头有一份职位描述和十份简历需要公平比较，却没有简单的办法， 把一份候选人名单的评判依据拿回原始记录去核对。iMBrace 把职位描述转化为一组经过认可的筛选 标准，用每份简历自己的原文作为证据，对照这些标准为每份简历打分，并给出一份经过排序、招聘 人员可以质疑也可以信赖的候选人名单。 ## 具体流程，一步步来看 完整的过程是这样的： 1. 招聘人员从一份职位描述和十份简历开始——这次要招聘的是一位客户成功经理。 2. “文档模块”（DocIQ），也就是 iMBrace 的文档阅读器，读取这份职位描述，提取出其中的要求。 画面：一条职位描述记录打开在数据表中，各项要求被提取为字段 *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　职位描述中的各项要求，被读取为“Requirement Lines”字段。* 3. 一个名为 Criteria Architect 的智能体，根据这些要求提出一组筛选标准，并标明每一条标准 的出处。 4. 招聘人员在一张表上查看这些标准——这是“数据表”（DataIQ）中的一张结构化表——勾选要 采用的标准，然后点击“保存”（Save）。 画面：标准清单数据表，每一行的批准字段都已打勾 *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　每一项标准都已批准，在“approved”字段打勾。* 5. 接下来录入十份简历。每份简历都成为一条独立记录，候选人的工作经历和教育背景会被完整读 取出来。 画面：一份简历落地成数据表中的独立记录，身份字段与工作经历都读取为结构化字段 *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　一位应聘者的记录，包括“Current / Most Recent Title”等字段。3　同一条记录的“Work History”字段。* 6. 第二个智能体 Evidence Assessor，依照已获批准的标准为每份简历打分，并引用简历中支持 每个分数的那句原文。 画面：标准证据数据表，显示某候选人一项评分背后引用的简历原文 *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　一项评分背后、引自简历的原文，在“quote_given”字段。* 7. 这些分数汇总到 Candidate Scorecard 上，按匹配程度从强到弱排序。 画面：候选人评分卡数据表，每位候选人都有一个匹配百分比 *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　每位候选人的匹配百分比，在“fit_pct”字段。* 8. 招聘人员在“分析模块”（InsightsIQ）——iMBrace 会附上依据来源作答的对话工具——里，向 第三个智能体 Screening Analyst 询问候选人名单，以及某位候选人为何排在这个位置。答案 会附带背后引用的简历原文。 画面：InsightsIQ 的回复：达到匹配度门槛的候选人入围名单 *1　侧边栏的“分析模块”（InsightsIQ）。2　Screening Analyst 的入围名单回复。* 画面：InsightsIQ 的回复，说明某候选人的排名与其简历缺口 *1　侧边栏的“分析模块”（InsightsIQ）。2　Screening Analyst 说明某候选人排名原因的回复。* ## 由人来决定的地方 在任何一份简历被打分之前，招聘人员先批准这些标准：在 Criteria 数据表上逐条勾选，然后点击 保存。这一步安排在打分开始之前，确保每份简历都是按照招聘人员真正认可的标准来衡量，而不是 智能体自行假设的标准。 ## 不写代码也能调整的内容 简历打分依据的标准，以及候选人需要达到的水平，都是数据表上的行。 | 行 | 控制的内容 | |---|---| | Criteria 数据表上的每一条标准 | 简历会被拿来对照的内容——必备、加分或警示项——以及招聘人员是否已批准这一条。 | | Level Expectations 数据表上的每一行 | 在某个方向上达到某个水平意味着什么，这样一条标准就可以指向某个水平，而不是一条固定规则。 | 新增、编辑或停用一行，下一份被打分的简历就会读取到这一变化——不需要重新搭建。 ## 试一试 如果你是合作伙伴，你的练习组织会自带已经安装好的简历筛选功能，使用 Lumenvale Software 的 职位描述和简历，你的合作伙伴资料包中的演示脚本，会带你实际跑一遍整个流程，从标准批准一直 到候选人名单。其他人都可以请自己的 iMBrace 联系人，在一个属于自己的组织上看这个流程演示。 ==================== see-it-work/sales-quoting.md ==================== --- level: '1' track: - sell - build - deploy verified_on: 2026-10-03 --- # 销售报价 Quillmoor Components 的销售团队要从一份庞大的产品目录中，为工业紧固件和配件报价，任何让毛利率低于 Quillmoor 底线的折扣，在报价发出之前都需要经理点头同意。iMBrace 把一句大白话的请求转化为一份标好价格的报价单。毛利率低于底线时，工作会停下来等经理；经理从一封邮件里答复，同一个工作就会接着往下走，把完成的文档发给提出请求的人。 ## 具体流程，一步步来看 完整的过程是这样的： 1. 销售人员用大白话向名为 Sales Quoting 的智能体提出报价请求：客户是谁、要哪些产品、数量各是多少。他们也可以附上自己的邮箱地址，完成的文档就会发到那里；没有附上时，文档会发给销售窗口。 2. 这个智能体读取 SQ Catalogue 和 SQ Pricing Rules 这两张表——即“数据表”（DataIQ）里的结构化表——分别存放着 Quillmoor 的产品和定价规则。 画面：SQ Catalogue 数据表列出 Quillmoor 的产品，含 SKU *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　“SQ Catalogue”数据表，Quillmoor 的产品与 SKU。* 画面：SQ Pricing Rules 数据表，含 approval_threshold 折扣规则 *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　折扣规则行，在“approval_threshold”字段。* 3. 它算出报价内容，并逐行写入 SQ Quotations 和 SQ Quotation Lines 这两张数据表。 画面：InsightsIQ 的回复：一份逐行定价、含总额的新报价单 *1　侧边栏的“分析模块”（InsightsIQ）。2　Sales Quoting 智能体的回复：逐行定价的新报价单。* 4. 接着由 iMBrace 自己，根据已写入的各行明细检查毛利率——而不是听智能体怎么说。毛利率达到底线的报价单不需要批准：它的文档会自动生成，并通过邮件发给提出请求的人。 5. 毛利率低于底线的报价单则会等待。它的状态显示为等待批准，背后的工作流程（iMBrace 中一旦触发就会自行运行各个步骤的引擎）会在决策点暂停。在“流程运营模块”（FlowOps）里，这份报价单的运行会标示为 Paused（已暂停）：它没有失败，也还没有完成，而是停在原处，等一个人答复。 画面：SQ Quotations 数据表，一行报价单的状态为 awaiting approval *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　报价单自身的状态：awaiting approval（待批准）。* 画面：流程运营模块的运行列表，这份报价单的运行标示为 Paused（已暂停） *1　“行动模块”（Actions）>“流程运营模块”（FlowOps）。2　这份报价单的运行，标示为 Paused（已暂停）：它正在等经理处理。* 6. 经理会收到一封邮件。那是一张卡片，载明做决定所需的一切——客户、明细、折扣、毛利率、总额和政策底线——并带有两个按钮：“批准”和“拒绝”。 画面：经理收到的批准邮件：一张卡片列出客户、折扣、毛利率、总额和政策底线，并带有“批准”和“拒绝”按钮 *1　卡片：客户、折扣、毛利率、总额和政策底线。2　“批准”和“拒绝”按钮。* 7. 每个按钮都会打开一个页面，显示所选的结果。仅仅打开页面，不会决定任何事；只有点击页面上的“确认”，才会记录这个决定。一旦有一个答案被确认，另一个按钮就会失效，所以一份报价单只会有一个答案。 画面：从“批准”按钮打开的确认页面：显示报价单、客户和总额，以及一个“确认”按钮 *1　所选的结果，以及它适用的报价单。2　“确认”按钮：点击之前，不会决定任何事。* 画面：点击“确认”之后显示的页面：报价单已批准，文档正在发出 *点击“确认”之后的页面：报价单已批准，文档正在发送给提出请求的人。* 8. 同一次运行会从停下来的地方接着往下走。平台会记录是谁批准、何时批准——也就是 Approved By 和 Approved At，这两列智能体无法写入——接着生成 PDF 和 Excel 文件，并通过邮件发给提出请求的人；如果一开始没有附上地址，则发给销售窗口。 画面：流程运营模块的运行列表，同一次运行现在标示为 Succeeded（成功） *1　“行动模块”（Actions）>“流程运营模块”（FlowOps）。2　同一次运行，现在标示为 Succeeded（成功）：它从等待的地方接着往下走，并且完成。* 画面：SQ Quotations 数据表，该行状态为 approved，且 Approved By 与 Approved At 已填写 *1　“知识模块”（Knowledge）>“数据表”（DataIQ）。2　这份报价单的行：状态为 approved（已批准），Approved By 与 Approved At 已填写。* 画面：提出请求的人收到的邮件：报价单已批准、可以发送，附有一份 PDF 和一份 Excel 文件 *1　告知提出请求的人，报价单已批准、可以发送的邮件。2　两个附件：PDF 和 Excel 文件。* 如果经理改点“拒绝”，这个拒绝会被记录下来，不会生成任何文档，并且会通知提出请求的人。 ## 由人来决定的地方 毛利率低于底线的报价单，必须等经理决定之后，才能发出任何东西。它会停在这一步，是因为规则本身不允许的折扣，理应始终由人来决定——并且每一次都由 iMBrace 自己按同样的方式核实，而不是依赖人的记忆。 经理在自己本来工作的地方做决定：收件箱，事实和两个按钮就在眼前。在他们答复之前，不会有任何东西发出去。如果一直没有人答复，报价单会保持暂停、清晰可见——在它自己的数据表上，也在“流程运营模块”里——也不会发出任何文档。等他们答复时，同一次运行会继续下去——不是重新开始——并把事情做完。 这就是这个用例要展示的：iMBrace 在人做决定的期间，替这次运行保留它的进度，等对方答复再接着往下走。这次运行接触的，是人、消息和文档——一位经理、一封邮件，以及一份完成的报价单。 ## 不写代码也能调整的内容 报价单所依据的规则，以及 Quillmoor 出售的每一件商品，都是数据表上的行。 | 行 | 控制的内容 | |---|---| | SQ Pricing Rules 数据表上的每一条规则 | Quillmoor 期望的毛利率，以及低于多少就必须由经理批准的毛利率底线。 | | SQ Catalogue 数据表上的每一件产品 | Quillmoor 出售的商品，以及对应的价格。 | | SQ Terms 数据表上的每一行 | 出现在每份报价单上的措辞，例如有效期、交付和付款条款。 | 修改一行，下一份写出的报价单就会读取到这次更新——不需要重新搭建。 ## 试一试 如果你是合作伙伴，你的练习组织会自带已经安装好的 Sales Quoting 功能，使用 Quillmoor Components 的产品目录和定价规则，你的合作伙伴资料包中的演示脚本，会带你实际跑一遍整个流程，从第一次请求，经过经理通过邮件批准，到提出请求的人收件箱里那份完成的报价单。其他人都可以请自己的 iMBrace 联系人，在一个属于自己的组织上看这个流程演示。 ==================== build-it/index.md ==================== --- level: '2' track: - build --- # 动手构建 课程前面的级别讲解了 iMBrace 是什么，并展示了一个用例从头到尾的运行过程。这一级由你亲自动手构建一个。 ## 这一级能让你收获什么 学完之后，你就能用自己已经在用的任意 AI 编程工具，在一个测试组织上构建出一个可运行的小型退货台，并让它等待人的决定。要做到这一点，不需要任何人把源代码交给你——你只需要一个测试组织、一个密钥，以及通过 MCP 连接好的编程工具。 - [设置你的编程工具](/zh-cn/learn/build-it/set-up-your-coding-tool.md)——测试组织与密钥，以及把你的编程工具连接到该组织。先做这一步。 - [在 iMBrace 上进行 Vibe Coding——动手构建](/zh-cn/learn/build-it/vibe-coding-tutorial.md)——文字教程。请按顺序跟做；它的设计就是让你在一个真实的测试组织上从头到尾走一遍。 - [让它等待人的决定](/zh-cn/learn/build-it/make-it-wait-for-a-person.md)——第二次动手：从已经完成的退货台开始，让它通过邮件询问一个人并等待答复，在此之前不向客户承诺任何事。 - [与 AI 编程工具协作](/zh-cn/learn/build-it/working-with-ai.md)——让你的工具构建出的成果保持可信的立场与护栏。 ## 开始之前 - 一个测试组织和一个 API 密钥。绝不能使用生产密钥。 - 任意能够保持 MCP 连接、并能读取文本文件的 AI 编程工具。本教程刻意不指定具体工具——你现在用的是哪一个，它就能配合哪一个。 - 教程大约一小时。“让它等待人的决定”是第二次动手，需要两个你能读取的邮箱地址。 ## 完成这一级之后 第 3 级“构建得好”，是这一页所教的这些习惯背后的方法：为什么每一条都重要、缺了它会是什么样子，以及如何在客户发现之前先一步看出差别。第 2 级让你构建出一个能运行的智能体，第 3 级则决定它是否值得交付。 ==================== build-it/set-up-your-coding-tool.md ==================== --- 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 返回。 如果两者都和你在平台上看到的一致，说明设置已经完成。如果任何一个失败了，那就是凭证或连接 方面的问题；先在这里解决，再动手构建任何东西。 ## 接下来 [教程](/zh-cn/learn/build-it/vibe-coding-tutorial.md) 会用你的工具一步步构建一个能实际运行的小型智能体。 [与 AI 编程工具协作](/zh-cn/learn/build-it/working-with-ai.md) 讲的是让它构建出的东西保持可信的那套原则。 ==================== build-it/vibe-coding-tutorial.md ==================== --- level: '2' track: - build verified_on: 2026-09-30 --- # Vibe coding on iMBrace - 动手构建 这是课程的第 2 级：动手构建。前面的级别展示一个完整运作的用例；本页则由你亲自动手构建一个。 完成后，你会在自己的测试组织上得到一个能运行的小型退货台：两张数据表、一条任何人都能编辑的退款规则、一个计算步骤，以及一个通过对话接收退货的助手。它刻意做得很小。重点不在这个退货台本身，而在四个习惯——它们让你在 iMBrace 上构建的任何东西都值得信赖，第 3 级“构建得好”会对此深入讲解。下一课[让它等待人的决定](/zh-cn/learn/build-it/make-it-wait-for-a-person.md)在这个退货台的基础上继续，并加上第五个习惯：在向客户承诺任何事之前，先由一个人做决定。 ## 你将构建什么 设想一家虚构公司 Harbor Bicycle Co.，在网上销售并维修自行车。你要为它构建退货台。一位客户写信要求退货。这个退货台应当： 1. 把这次请求记录为数据表上的一行，而不是把它留在聊天记录里。 2. 根据 Harbor 任何人都能编辑的规则算出退款金额，而不是靠模型自己做运算。 3. 由一个助手通过对话接收退货：它记录这笔退货，不说出任何退款金额，也不做出任何承诺——因为还没有人做出决定。 退货台刻意停在这里。Decision、Decided by 和 Decided at 保持为空：它们是[让它等待人的决定](/zh-cn/learn/build-it/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，[设置你的编程工具](/zh-cn/learn/build-it/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 步创建了自己的数据表后，按名称去里面找它就好。不管是哪种情况，你都应该还会看到一份关于邮件的原生步骤简短列表，很可能还夹杂着你没问到的其他渠道。把这份列表读一遍。这是第一个习惯：在考虑自己写一个之前，先找到平台已经提供的步骤。工具从零写出的步骤，需要你持有一个凭证、维护一段代码；原生步骤两样都不需要。这份列表里的邮件步骤，正是[让它等待人的决定](/zh-cn/learn/build-it/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，是一个人所给答复的记录：本课里没有任何东西会填写它们，由[让它等待人的决定](/zh-cn/learn/build-it/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。目前还没有人审核这次申请；[让它等待人的决定](/zh-cn/learn/build-it/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 仍为空：智能体没有办法写入它。 如果以上任何一条不成立，这比一个看起来没问题、实际上却有问题的构建更有价值。修好出问题的那一处，再检查一遍。 ## 接下来做什么 - 继续做[让它等待人的决定](/zh-cn/learn/build-it/make-it-wait-for-a-person.md)，这是第二次动手。它从这个退货台开始，让退货台在向客户承诺任何事之前，先通过邮件询问一个人。 - 尝试第二种状况——比如少了包装盒退回的零件——并添加第二条规则行。确认你能改变退款比例，而不用碰工作流程或智能体。 - 阅读第 3 级“构建得好”，了解这些习惯背后更完整的方法——它讲的是如何让这样的构建经得起交到真实客户手上的考验，而不只是停留在测试组织里。 - 关于 SDK、CLI 或 MCP 连接本身的任何内容，[engineer.imbrace.co](https://engineer.imbrace.co/zh-cn) 是保持最新的信息来源——本页的内容会先过时，那个网站不会。[设置你的编程工具](/zh-cn/learn/build-it/set-up-your-coding-tool.md)有完整的设置说明。 ==================== build-it/make-it-wait-for-a-person.md ==================== --- level: '2' track: - build verified_on: 2026-10-02 --- # 让它等待人的决定 本课让[教程](/zh-cn/learn/build-it/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. 的真实系统——在把它演示给任何人看之前，请换成你自己的公司、审核人和措辞。 ## 你需要什么 - 你在[教程](/zh-cn/learn/build-it/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 步里看到带着真实链接的页面。 如果你看到的不是这一句话，就把你看到的原样告诉你的工具，并要求它让这个工作流程以一个无需登录的网页来作答，然后在继续之前，再把地址打开一次。 页面背后的规则：邮件里的链接不是一项决定。打开链接只会显示一个页面；只有“确认”才会做出决定。随机代码从不被保存，保存的只有它的指纹，而存放指纹的数据表是私有的。[人工批准](/zh-cn/learn/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 里。 - 阅读[人工批准](/zh-cn/learn/build-it-well/human-approval.md)，了解本课背后的方法：决定放在哪里、什么让关卡真正守住，以及如何证明它从头到尾都接上了线路。 - 参见[构建模块](/zh-cn/learn/build-it/building-blocks.md)，了解退货台的每一个部分在屏幕上的位置：数据表、工作流程、智能体和邮件连接。 - 关于 SDK、CLI 或 MCP 连接本身的任何内容，[engineer.imbrace.co](https://engineer.imbrace.co/zh-cn) 是保持最新的信息来源——本页的内容会先过时，那个网站不会。[设置你的编程工具](/zh-cn/learn/build-it/set-up-your-coding-tool.md)有完整的设置说明。 ==================== build-it/working-with-ai.md ==================== --- 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 连接，用在“这里存在什么”或“发生过什么”这类问题上——见 [设置你的编程工具](/zh-cn/learn/build-it/set-up-your-coding-tool.md)。 ## 准则 - **工作流程、代码步骤、提示词或已提交的文件里都不能出现凭证。** 凭证只存放在组织自己的 连接存储中，或者存放在一个绝不提交的本地 `.env` 文件里。 - **代码步骤是纯函数**——数字进去，结果出来，没有网络调用，没有密钥——如果做不到，就 明确说明原因。 - **拒绝回答本身也是一种数据，不是错误。** “我没找到”是一个有效、有用的答案。 - **被跳过的检查绝不算通过。** 如果一项测试没能运行，就如实说它没有运行。 - **测试数据、日志、提示词或示例中都不能出现个人数据。** 都用虚构的。 - **写给一个陌生人看。** 用平实的句子，不用只有当事人才懂的简写或黑话。 ## 最重要的几个习惯 1. **业务成果优先。** 谁会用它、今天卡在哪里、它能带来什么——一个漂亮地回答了没人问过 的问题的方案，就是一个错误的方案。 2. **人先画草图。** 在工具提出设计方案之前，先让人把用例画出来——形状、各个部分，以及 哪里由人来做决定。这样设计才始终属于这个人。 3. **带着证据表达不同意见。** 当工具认为这个人错了，它应立即说出来，并给出证据，而不是 默默按要求去做。 4. **每一个论断都要有依据。** 一条数据表记录、一次运行的 id、一段粘贴出来的输出——没有 依据，就不能下论断。 5. **改正记录时要注明日期。** 当一条发现或一条决策记录后来被证明是错的，就地注明日期 说清楚，并保留原文可见。 6. **由另一个人来评审。** 在发布之前，由没有参与构建的人跑一遍 [评审清单](/zh-cn/learn/build-it-well/review-checklist.md)。 7. **流程的繁简要与改动的大小相称。** 一次小改动，只需要一条小记录。 ## 让委派保持浅层 如果你的工具把工作交给了它自己的助手，就把交接控制在最上一层，给每个助手一份完整的任务 说明，并亲自核实每一个结果：当某个助手说它修好了什么，就打开文件亲自看一看。 ## “完成”意味着什么 另一个人能够安装使用的成果、一份他们能照着做的说明、一个他们能运行的测试，以及对每个部分 如实标注的状态。 ==================== build-it/building-blocks.md ==================== --- level: '2' track: - build verified_on: 2026-09-29 --- # 构建模块 iMBrace 上的每一个用例，不论外观差异有多大，都是用同样的五样东西搭建起来的：一张数据表、一个智能体、一个文档模型、一个工作流程和一个渠道。本页将逐一说明它们的名称、用途，以及它们在产品中的位置，让你第一次打开培训组织时，侧边栏上的一切都不再陌生。最后还会介绍扩展这些部件、或把它们交给别人使用的三种方式：技能、MCP 连接，以及安装模块。 ## 数据表 数据表是一张由你自行定义结构的表格——有行，也有按类型定义的字段，就像一张轻量版的 CRM 表格。它用来保存构建工作需要记住的任何内容：一份退货申请清单、一份已报价的报价单、一组可供他人自行编辑的规则。 在侧边栏中，它位于**“知识模块”（Knowledge）>“数据表”（DataIQ）**下（SDK 与其权限范围中称之为 board，或 databoard；产品在屏幕上显示的名称是 DataIQ）。其余每一个构建模块都会读写数据表：工作流程的每一个步骤、智能体唯一可调用的那个精简工具，以及文档模型自身的提取结果，最终都会落在同一张数据表上。 画面：数据表以行与带类型字段的形式打开 *1 “知识模块”（Knowledge）>“数据表”（DataIQ）。2 数据表以行与带类型字段的形式打开。* 让数据表值得信赖的习惯：把业务人员可能需要调整的规则——阈值、费率、上限——作为可编辑的行放在数据表上，而不是写死在智能体自己的指令里。[八项原则](/zh-cn/learn/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”标签页，每张卡片一个助手。* 让智能体值得信赖的习惯：只给它一个专用于某件事的精简工具，绝不给它整张数据表的权限，这样它可以记录一项申请，却永远无法自己写下批准该申请的决定。[人工批准](/zh-cn/learn/build-it-well/human-approval.md) 说明了为什么智能体绝不能自己写下那个决定。 用代码实现：[智能体](https://engineer.imbrace.co/zh-cn/reference/ai-agent/)。 ## 文档模型 文档模型告诉提取功能要从文件里提取什么内容。它的作用是把一份非结构化的文档——发票、表单、扫描的装箱单——转换成数据表可以保存的结构化字段。 在侧边栏中，它位于“知识模块”下的**“文档模块”（DocIQ）**，在**“文档模型”（Document Models）**标签页中。它提取出的内容会以行的形式落在数据表上，也就是工作流程或智能体随后读取的那张数据表。 画面：文档模块的“文档模型”标签页，展开其中一个模型的提取字段 *1 “文档模块”（DocIQ） > “文档模型”（Document Models）。2 文档模块的“文档模型”标签页，展开其中一个模型的提取字段。* 让文档模型值得信赖的习惯：先采用平台自带的默认模型，再考虑另写新模型，并让提取功能对准某一张数据表本身的字段，而不是把模型的选择交给运气。[文档模型](/zh-cn/learn/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 流程运营模块的工作流程列表。* 让工作流程值得信赖的习惯：优先用平台自带的现成步骤搭建，如果确实需要自己写步骤，就保持它的纯粹——只基于传入的值进行计算，不持有任何自己的凭据。[原生优先](/zh-cn/learn/build-it-well/native-first.md) 说明了这样做的好处。 用代码实现：[工作流程](https://engineer.imbrace.co/zh-cn/reference/workflow/)。 ## 渠道 渠道是用户实际联系到智能体的地方——网站聊天窗口、WhatsApp、电子邮件，或其他已连接的消息应用——它也是回复送达的地址。 在侧边栏中，它位于“行动模块”下的**“连接模块”（ConnectIQ）**，在**“渠道设定”（Channels）**标签页。渠道是与智能体对话开始的方式，工作流程也可以把渠道的某个事件当作自己的触发条件。 画面：连接模块的“渠道设定”标签页，列出网页小部件和各消息渠道 *1 “连接模块”（ConnectIQ） > “渠道设定”（Channels）。2 连接模块的“渠道设定”标签页，列出网页小部件和各消息渠道。* 让渠道值得信赖的习惯：把它的登录信息作为组织自己的一个连接来设置一次，绝不把它当作一个值放进工作流程里。需要有人登录的连接（例如托管邮件服务）由一个人为整个组织设置一次；邮件服务器连接则用服务器自身的信息配置一次即可。[原生优先](/zh-cn/learn/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/)。[设置你的编程工具](/zh-cn/learn/build-it/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/)。 ## 它们如何协同运作 教程和[让它等待人的决定](/zh-cn/learn/build-it/make-it-wait-for-a-person.md)中，Harbor Bicycle Co. 的退货台，一次性用到了所有构建模块。客户与 Return Desk Assistant 对话。这个智能体负责倾听，它唯一的技能——一个叫 Log return request 的工作流程——会在 Return Requests 数据表上写入新的一行。第二个工作流程根据 Refund Rules 数据表算出退款金额。还有一个工作流程去询问值班经理：它通过邮件发出一张带有“批准”（Approve）和“拒绝”（Reject）按钮的卡片，然后等待。每个按钮都会打开一个页面，由经理在上面确认；随后这个工作流程从暂停的地方接着往下走，把决定、审核人的姓名和时间记录在这一行上，并给客户发邮件。这个场景不需要用到文档模型，因为没有任何东西是以文件形式进来的——如果退货是以扫描装箱单的形式进来，就会先由文档模型读取，再以一行的形式落在同一张数据表上。 Harbor 的每一个构建模块，都可以打包成一个模块，安装进另一个组织，它的数据表、工作流程和智能体设置会一起带过去，让那个组织自己的管理员打开并调整。而最初让编程工具搭建出这一切的那同一个 MCP 连接，之后也能用来检查结果：列出数据表，读取工作流程最近一次的运行记录。 想亲手搭建一遍，一步一步来，请见[教程](/zh-cn/learn/build-it/vibe-coding-tutorial.md)，然后在[让它等待人的决定](/zh-cn/learn/build-it/make-it-wait-for-a-person.md)里，让退货台去等待一个人的决定。 ==================== build-guide.md ==================== --- level: '2' track: - build --- # AI 工具的构建指南 iMBrace 构建指南就是本课程的[构建得好](/zh-cn/learn/build-it-well/index.md)各页、每一个好的 iMBrace 构建成果背后的原则，加上[设置你的编程工具](/zh-cn/learn/build-it/set-up-your-coding-tool.md)、[教程](/zh-cn/learn/build-it/vibe-coding-tutorial.md)与[让它等待人的决定](/zh-cn/learn/build-it/make-it-wait-for-a-person.md)——全部打包成 AI 编程工具自己就能读取的纯文本文件，而不是一份需要你读完再讲给它听的页面。 ## 适用对象 任何正在用 Claude Code、Codex、Cursor，或其他能读取项目文件的 AI 编程工具，在 iMBrace 上构建的人。 ## 使用方式 先下载下方的指南，再把你的工具指向它。三种简短做法： **Claude Code。** 把指南解压到你的项目里。它自己的 `CLAUDE.md` 只有一行：`@AGENTS.md`，所以只要你项目的 `CLAUDE.md` 会读到它——不论是直接读到，还是通过你自己加的一行 `@` 指向解压后的文件夹——Claude Code 就会顺着读到 `AGENTS.md`。也可以改用技能：指南里也带了一份 `SKILL.md`，所以把解压后的文件夹安装成 Claude Code 技能，效果一样，而且完全不用改动 `CLAUDE.md`。 **Codex 及其他会读取 `AGENTS.md` 的工具。** 把指南解压，让它的 `AGENTS.md` 落在你项目的根目录，或者在你自己根目录的 `AGENTS.md` 里加一行指向它。任何已经遵循这个惯例的工具，都会用同样的方式读到它。 **Cursor。** 指南带了一个 `.cursor/rules/imbrace.mdc` 文件。把指南解压到你的项目里，Cursor 就会读到这条规则，而它会指向 `AGENTS.md` 本身的方法内容。 ## 事实从哪里来 这份指南只讲方法：如何把设计与构建做好。它从不复制 SDK、CLI 或 MCP 的事实，因为复制来的事实会过时。它会告诉你的工具实时抓取 [https://engineer.imbrace.co/llms.txt](https://engineer.imbrace.co/llms.txt)，并读取它指向的那一页。把你的工具连接到测试组织的方式也一样：见 [MCP 指南](https://engineer.imbrace.co/zh-cn/mcp/overview/)。 ## 下载 - [AI 编程工具的构建指南（.zip）](https://engineer.imbrace.co/learn/imbrace-build-guide-community.zip) - [整门课程，给 AI 工具读取（llms-full.txt）](https://engineer.imbrace.co/zh-cn/learn/llms-full.txt) - **可浏览的文件**——`AGENTS.md` 及其他文件，都在 [engineer.imbrace.co/learn/agent-pack/README.md](https://engineer.imbrace.co/learn/agent-pack/README.md) 之下 - **整份指南合并成单个文件**，适合只读取单一文档、而非整个文件夹的工具：[英文](https://engineer.imbrace.co/learn/llms-full.txt)、[繁体中文](https://engineer.imbrace.co/zh-tw/learn/llms-full.txt)、[简体中文](https://engineer.imbrace.co/zh-cn/learn/llms-full.txt) ==================== build-it-well/index.md ==================== --- 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）**——凭证、密钥和敏感数据都留在配置中，绝不进入构建自身的逻辑。 ## 这一页讲什么，其余页面讲什么 | 页面 | 内容 | |---|---| | [八项原则详解](/zh-cn/learn/build-it-well/the-eight-principles.md) | 每项原则的完整说明：它的含义、做得好是什么样子、常见的出错方式，以及你该向自己的构建提出哪些问题。 | | [用例形态](/zh-cn/learn/build-it-well/use-case-shapes.md) | 业务用例反复出现的九种形态，以及每一种通常由哪些部件组装而成。 | | [人工批准](/zh-cn/learn/build-it-well/human-approval.md) | 一个人如何从带有“批准”和“拒绝”按钮的邮件做出决定，并在页面上确认——以及为什么聊天回复不算是一项决定。 | | [原生优先](/zh-cn/learn/build-it-well/native-first.md) | 为什么要先用平台自身的能力、再考虑写代码，以及这样做能带来什么好处。 | | [文档模型](/zh-cn/learn/build-it-well/document-models.md) | 如何选择让“文档模块”（DocIQ）从文档中提取什么内容：优先采用默认模型，其次扩展它，最后才考虑自己编写。 | | [反模式](/zh-cn/learn/build-it-well/anti-patterns.md) | 反复出现的构建错误、每一种的代价，以及对应的修复方法。 | | [审查清单](/zh-cn/learn/build-it-well/review-checklist.md) | 同样的八项原则审查，做成一份清单，供你在交付前对照自己的构建逐项核查。 | 这些都不需要死记硬背。找到与你眼前这个决定相匹配的页面，用它提供的问题来检视，然后继续前进。 ==================== build-it-well/the-eight-principles.md ==================== --- 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. 分别试一试批准、拒绝，以及放着不管不处理。在每一种情况下，流程是否都会自行继续下 去——完成任务，或者把结果报告出来——不需要任何人问第二遍？ 参见[人工批准](/zh-cn/learn/build-it-well/human-approval.md)，了解人如何从一封邮件做出决定、确认页面做了什么，以及为什么单凭聊天回复算不上一项决定。 ## 6. 原生优先（Native-first） **含义。** 如果平台已经提供了完成某件事的方式——搬运数据、发送消息、等待某个人处理、连接到 另一个系统——就用平台提供的方式，而不要自己写自定义代码去做同样的事。如果你能 明确说出某项能力“这是平台的一个功能”，那么用自定义代码把它重新做一遍，只会把这项 能力藏起来、随着时间推移而老化，并且通常最终还需要一个内置方式原本根本不需要的凭证。 **做得好是什么样子。** - 构建是由平台自身的构件一步步搭起来的，非开发者也能看懂。 - 与其他系统的连接，保存在平台自身的连接存储里，权限范围明确、可以复用，绝不会被嵌入到构 建的逻辑内部。 - 在确实需要自定义代码的地方，它只对拿到的输入做计算，不会自作主张地去调用其他任何东西。 - 任何例外情况都被记录下来：考虑过哪项能力、为什么没有使用它，以及满足什么条件就可以把这 段自定义代码退役。 **常见的出错方式。** - **自建捷径。** 用自定义代码去做平台本来就已经提供的事，通常是因为事先没有人查证 过。它往往需要一个内置方式本不需要的凭证，而且构建一旦搬到别处，它就会立刻失效。 - **被包装过的脚本。** 一大段自定义逻辑，外面只裹着薄薄一层 AI。它能算出正确答案，却完全说 明不了这个设计本身是否站得住脚。 - **悄无声息的凭证。** 一个登录信息或密钥被嵌在构建的某个角落，没有人记录下来，于是也就没 有人再回头把它清理掉。 **该问自己的问题。** 1. 打开这个构建，一个非开发者能不能说出每一步在做什么？ 2. 在构建里搜索任何看起来像凭证或访问密钥的东西，结果会找到什么？ 3. 对每一段自定义代码：当时考虑过平台的哪项能力，为什么它不够用？ 4. 把这个构建搬到另一个账户或环境中，会有什么东西失效？ 更多内容见[原生优先](/zh-cn/learn/build-it-well/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 模型会读取这个构建的数据？其中有没有哪一个是在部署之外的？ ==================== build-it-well/use-case-shapes.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 用例形态 大多数业务用例之间的差异，并不像乍看之下那么大。见得多了，就会发现它们能归纳为数量不多的几种反复出现的形态。找到与你手头问题相符的形态，你就有了一份可以组装的初稿——一个可以拿来讨论、而不是最终定案的设计。 下面每一种形态，先说明它看起来是什么样子，再说明它通常由哪些部件组装而成。这里说的是部件的种类和作用，而不是具体的产品——真正的构建部件在平台自身的部件库中。 ## 1. 交易处理器 **它是什么样子：** 有人用大白话提出请求，想要一个报价或配置好的东西——一份报价单、一次预订，或者为他们量身核算出的具体方案。 **通常由以下部件组装而成：** - 一个针对此类交易调优过的智能体 - 一项查找现有记录的技能 - 一项搜索匹配记录的技能 - 一项执行计算、并展示所用全部输入的技能 - 一项保存结果记录的技能 - 一项根据模板生成文档的技能 - 一项在任何内容发出之前，先通过带确认页面的邮件请人批准的技能 - 一项将完成的文档发送给请求人的技能 - 在容量有限的场景下，一项按真实剩余可用量（而不仅仅是原始数量）预留名额的技能 ## 2. 信息提取后台 **它是什么样子：** 单据不断送达——发票、申请表、表单——需要被核对后变成结构化的记录。 **通常由以下部件组装而成：** - 一个读取传入文档的智能体 - 平台自带的文档接收功能 - 一项在读取前把文档拆分成各个独立部分的技能 - 一项将一条记录与另一条记录进行比对的技能，包括涉及第三方来源时的三方核对 - 一项按规则核对提取值的技能 - 一项查找重复记录的技能，即便写法略有不同也能识别 - 一项保存记录的技能 - 一项在任何未能明确通过时请人做出决定的技能 - 一项发送结果消息的技能 - 一轮独立的复核，用来审计第一轮处理的结果 ## 3. 数据洞察台 **它是什么样子：** 人们用大白话就企业内部已有的数据提出问题。 **通常由以下部件组装而成：** - 一个专为回答数据类问题而构建的智能体 - 一项查询底层记录、并返回其实际执行的查询语句（而不只是给出一个看不到推导过程的答案）的技能 - 一项对记录进行分组汇总的技能 - 一项执行计算的技能 - 一项通过邮件发送答案的技能 - 一项自动化，在新记录一出现就将其关联回其父记录 当某个数字必须可核实时，使用上面的查询技能——它会连同答案一起返回其执行的查询语句，方便任何人事后核对这个数字。 ## 4. 对话式入口 **它是什么样子：** 任何人都可能从某个渠道进来——一个聊天小组件、一款消息应用、一个收件箱——构建必须先弄清楚对方是谁，才能做任何有用的事。 **通常由以下部件组装而成：** - 一个驻守在该渠道的智能体 - 一项核实发送者真实身份的技能 - 一项查找匹配记录的技能，并在找不到匹配时提供合理的兜底方案 - 平台自带的文档接收功能，用于处理以文件形式发来的内容 - 一项对传入的自由文本进行筛查、识别其中不应自动执行的内容的技能 - 一项请人做出决定的技能 - 一项签发一次性访问链接的技能 - 一项发送消息的技能 - 一项保存记录的技能 ## 5. 多智能体审查团 **它是什么样子：** 一个案例需要依据规则手册进行判定，而这个判定确实需要不止一种视角——由一名主导者统筹协调多位专才。 **通常由以下部件组装而成：** - 一个主导智能体、一个或多个专才评估智能体、一个规则手册读取器，以及一个报告撰写器 - 一项查询底层记录的技能 - 一项按规则核对数值的技能 - 一项将引用的条目与其来源进行核对的技能 - 一项比对记录的技能 - 一项执行计算的技能 - 一项保存结果记录的技能 - 一项请人做出决定的技能 - 一轮针对整个案例的独立审计 ## 6. 自动建档型 CRM **它是什么样子：** 笔记、通话记录和消息不断涌入，需要转化为记录，再由人确认，而不是靠人手动录入。 **通常由以下部件组装而成：** - 一个读取传入笔记和消息的智能体 - 一项把传入文档拆分成各个独立部分的技能 - 一项核实引用条目的技能 - 一项保存记录的技能，包括保存归属于它们的任何嵌套子记录 - 一项持续记录变更内容和时间的技能 - 一项在任何内容被视为最终结果之前请人确认的技能 - 一项撰写简短报告的技能 - 一项撰写并发送邮件的技能 - 一项自动化，会等待一连串相关活动告一段落后再采取行动，而不是在第一项一出现就立刻触发、结果其余项目一到就出错 ## 7. 合同或文档管理 **它是什么样子：** 一份长文档——合同、协议、长篇备案文件——驱动出一条工作记录，以及一份围绕它需要发生的事项排期表。 **通常由以下部件组装而成：** - 一个（有时是两个协同工作的）读取文档的智能体 - 一项拆分文档并将其路由到正确处理流程的技能 - 一项提取大量字段、并将结果与完整字段清单核对的技能 - 一项核实引用条目的技能 - 一项按规则核对数值的技能 - 一项填写模板的技能 - 一项签发一次性访问链接的技能 - 一项存储结果文件的技能 - 一项按固定节奏运行整个周期的定时自动化 ## 8. 知识套件 **它是什么样子：** 人们就一批文档——政策、手册、过往来往信函——提出问题。 这是唯一一种最直觉的做法往往是错误做法的形态，因此值得把它拆成两类来看： - **“我该怎么做”**这类是真正的搜索问题。平台自带的、针对一批文档的内置检索功能就能很好地处理，不需要在上面再搭建任何东西。 - **“有多少个”**或**“哪份文档在第几页提到了这一点”**这类是计数和引证问题，最好由记录来回答，而不是靠检索。把每一页都索引为一条独立记录，再用一项查询这些记录的技能和一项对其分组汇总的技能。这样一来，计数和引证就能做到精确无误。 ## 9. 治理能力展示 **它是什么样子：** 这类构建的重点在于展示谁可以看到什么——访问权限、脱敏和审计——而不是任何一笔具体的交易。 **通常由以下部件组装而成：** - 平台自带的访问管理、视图级脱敏、模型治理和读取审计 - 一项对智能体输出内容中的敏感字段进行脱敏的技能 - 一项筛查文本的技能 - 一项签发一次性访问链接的技能 - 一项对智能体自身答案进行的输出核查，作为平台视图级脱敏之外的第二道防线 ==================== build-it-well/human-approval.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 人工批准 每一个重要的构建，都有这样一个时刻：必须有人点头，某样东西才能发出去。请先设计这个时刻：要请谁决定、他们本来在哪里工作、眼前有哪份文档、他们看到什么，以及他们答复之后会发生什么。 ## 决定是一回事，做出决定的场合是另一回事 决定这部分的工作，是从底层记录中算出应当发生什么，如果还没有人做出决定就拒绝继续，并记下是谁决定的、决定了什么、什么时候决定的。这部分不会因构建而改变。 而做出决定的场合——一个人具体在哪里、以什么方式做出这个决定——按用例来选，但默认做法并不是可以随意挑的：一个人在自己本来工作的地方做决定。对大多数审核人来说，那就是他们的收件箱。 ## 默认做法：带有“批准”和“拒绝”的邮件 审核人会收到一封邮件，里面有做决定所需的一切：相关事实、文档本身（报价单、简历、合同）的链接或附件，以及建议的处理方式。下方是两个按钮，“批准”和“拒绝”。 1. 构建暂停下来，并给审核人发邮件。等待期间，不会有任何东西发出去。 2. 审核人阅读这封邮件，文档就在眼前。 3. 点击其中一个按钮，会打开一个确认页面，显示他们所选的结果。仅仅打开页面，不会决定任何事。 4. 只有在页面上点击“确认”，才会记录这个决定。另一个按钮随后就会失效，所以一个人只会给出一个答案。 5. 同一次运行接着往下走：完成工作——例如把文档发给销售人员——并告诉提出请求的人发生了什么。 在构建任何东西之前，先用五行字写下这个时刻：要请谁决定、他们本来在哪里工作、眼前有哪份文档、他们看到什么，以及他们答复之后会发生什么。然后记住三件事。 - **以人、消息和文档为主。** 这个时刻是一个人、一封邮件和那份文档，而不是一张表格。数据表只是它背后的记录。 - **邮件是一张卡片，而不是一条通知。** 如果审核人得另外打开别的东西才能做决定，就说明这张卡片缺了一项事实。 - **每一条分支，都要结束在提出请求的人看得到的地方：** 已批准、已拒绝、已过期、无人答复。 ## 其他方式，以及何时使用 | 场合 | 运作方式 | 适用场景 | |---|---|---| | **带确认页面的邮件** | 每种结果各一个按钮；点开按钮会显示一个页面，在上面确认才会写入决定 | 默认做法，适用于每一位在收件箱里工作的审核人 | | **记录上的一个字段** | 一个人在数据表上切换状态字段；保存之后，下一步就会触发 | 备用做法，只在审核人本来就每天在这张数据表上工作时才用。不适合一般业务人员 | 不要要求业务人员通过在数据表里选一个值来批准。那个值藏在一张他们没有理由打开的表格里，要保存后才会生效，也让人感觉不像是在做决定。 具体有哪些场合可用，取决于你的安装环境和版本；你的 iMBrace 联系人可以为你确认。无论选择哪一种，在依赖它之前，都要亲自以审核人的身份走一遍：他们收到邮件、打开、确认，然后构建把事情做完。 ## 不能变通的规则 **在聊天里友好地打一声“好”，本身并不算是一项决定。** 那只是流程控制——它可能只是让对话继续下去——但它不会留下任何持久的记录，让日后有人能够指出：这件事在这个时间，由这个人批准。决定是一条绑定到具体某一项的记录，记下了是谁在什么时候做出的决定。 还有两条值得牢记的规则： - **关卡自己算出答案。** 它会根据底层记录重新计算结果，而不是相信同一次互动中刚被告知的数字。一个只相信别人告诉它什么的关卡，会很乐意批准一个错误的数字。 - **没有决定，就没有输出。** 不是默认放行，也不是过一段时间超时就自动放行。只要还没有人做出决定，就不会有任何东西发出去。 ## 让关卡真正守住的细节 - **打开链接，不会决定任何事。** 人、邮件扫描程序或预览功能都可能打开它。访问只会显示页面；只有确认这一步才会做出决定。 - **每个人一封邮件、一组按钮。** 在你自己的记录上，记下这组按钮属于谁、他们何时确认，这样“由谁批准”永远来自你自己的记录。 - **第二个答案不会改变任何事。** 一旦有一个答案被确认，另一个结果就会失效，而且暂停之后的那一步，重复运行也是安全的。 - **确认页面如实呈现。** 只有在决定确实被记录下来之后，才显示“完成”；如果没有记录成功，就明确说出来。 - **等构建真的在等待答案时，才发出邮件。** - **智能体绝不能有写入决定的能力。** 用来记录决定的列，应当在记录创建时就取好起始值，并拒绝智能体之后对它的任何写入——只给智能体范围狭窄、碰不到这些列的工具。 - **“还没有结论”绝不能被当成“通过”。** 一项还没运行、或已经失败的检查，会让记录看起来和真正通过的一模一样。请在每一条记录上都打上结论，包括没问题的那些，并让此后每一步都等待这个结论、没有它就拒绝继续。 - **数据表里的编辑，要到点击“保存”（Save）之后才会生效。** 如果审核人确实使用数据表，请从已保存的状态测试这个关卡，并在给他们的操作说明里加上“点击‘保存’”这一步。 ## 证明关卡确实接上了线路，而不只是摆在那里 一个控制点的好坏，取决于它究竟绑定了什么。把这个场合接到真正依赖它的东西上，并以审核人的身份，把整条路径端到端实际走一遍：对每一种结果——批准、拒绝、无人答复——都启动一次运行，从他们实际会收到的那封邮件答复，然后确认工作已完成，或提出请求的人已被告知，而且不需要任何人再提示。在这件事做完之前，关卡都不算建好。 ==================== build-it-well/native-first.md ==================== --- level: '3' track: - build verified_on: '2026-09-23' --- # 原生优先 在写自定义代码去做某件事之前，先确认平台是不是已经能做到这件事。这不是风格上的偏好选择。它会直接影响你的构建运行起来要花多少成本、能不能安全地迁移，以及日后别人理解它有多容易。 ## 一句话讲清这个道理 如果一个人能够指着某项能力、把它说成平台的一项功能，那么这项能力几乎肯定已经内置在平台里了。你自己用自定义代码把它重新做一遍，会把它的实际作用藏到一段别人必须去读的代码背后，还往往会随着平台演进而逐渐落伍过时，而且很多时候最终还需要一个内置方式原本根本用不到的登录凭证。 ## 平台开箱即用通常已经提供了什么 这一类可正常运行的平台，出厂就自带大量现成的能力：读写结构化记录、通过常用渠道发送邮件和聊天消息、日历、电子表格、文件存储、处理传入的文档、暂停一个流程以等待人来处理、从一个流程调用另一个流程、在流程内部做路由和循环，以及干净地终止一次运行。与各类账户和其他系统的连接，都保存在平台自身的连接存储中——配置一次，由构建引用，绝不会被带进构建自己的逻辑里。 在写下第一行自定义代码之前，值得先查一查平台当前的能力清单，看看有没有现成的东西已经能完成这项工作。新的能力会不断持续上线，最安全的默认做法永远是先查看、再动手构建。 ## 什么时候自定义代码才真正站得住脚 以下两件事必须同时成立： 1. **没有任何内置能力能完成这项工作**，而且你能具体说出自己查过什么、为什么那些都不够用。 2. **这段代码是纯粹的**——它只对拿到手的值进行计算，本身不会带着自己的凭证去调用另一个系统。如果它确实需要触达另一个系统，也要通过平台自身的某个连接去做，而不是靠代码里嵌的一个密钥。 任何偏离原生优先原则的例外情况，都应该被明明白白地记录下来：考虑过什么、为什么没有采用，以及将来要满足什么条件才能让这段自定义代码退役。把这种例外当作一项临时的、有名有姓的债务来对待，而不是一个悄悄变成永久的选择——一旦平台上线了能做同样工作的内置方式，就立刻让它退役。 ## 为什么这件事比听起来更重要 - **构建里的任何东西都不应该保存凭证。** 一个只使用平台自身连接的构建，不包含任何登录信息、任何 API 密钥，任何这类东西都没有。这意味着这个构建本身可以被安全地分享、导出，或者迁移到另一个账户——里面没有任何东西需要被轮换、被脱敏或者让人担心。 - **一个使用内置能力构建出来的东西，非开发人员也能读懂。** 他们可以打开它，一步一步地看到每个部分在做什么，根本不需要打开任何代码。自定义代码则会把这一切藏到一堵只有开发人员才能读懂的墙后面。 - **它经得起迁移。** 把一个完全用内置能力构建出来的东西导出到另一个账户，不需要任何重新接线。一个把凭证写死在里面的构建则会失效——更糟的情况是，它悄悄地继续运行，用的却是错误账户的权限。像 Gmail 这样使用服务商登录的连接，由有权限的人在每个账户上完成一次授权即可；邮件服务器（SMTP）连接则是用服务器信息配置一次即可。 ## 好的样子是什么 - 这个构建在平台自身的视图里，能够一步步读下去，不需要打开任何代码就能看懂。 - 在构建的逻辑里搜索任何凭证类的东西，结果什么都搜不到。 - 如果有自定义代码，每一段都附有一条说明，写明考虑过哪项内置能力、为什么它不够用。 - 把这个构建迁移到另一个账户，不会改变它的任何行为。 ## 一个实际例子 以一个报价助手为例：发送完成后的文档完全不需要任何自定义代码——读取记录、按状态路由、格式化日期、发送邮件、更新记录，这些步骤全部都是内置的。审批环节的做法也是一样，用一个内置任务暂停流程、等人做出决定，然后自己接着往下走，把文档发出去。自定义代码通常只局限于少数几件事：算术运算、一次数据库查询、一次最终核查，以及文档本身的排版。 ==================== build-it-well/document-models.md ==================== --- level: '3' track: - build verified_on: '2026-09-23' --- # 文档模型 当“文档模块”（DocIQ）读取一份文档——一份简历、一张发票、一张采购订单——**文档模型**会告诉它要提取什么内容、填到哪条记录里。获得一个文档模型有三种方式，而且有严格的先后顺序。 1. **采用组织的默认模型。** 平台自带一个庞大的模型库，涵盖简历、发票、采购订单和入职核对清单等。采用一个默认模型不花任何成本，并且这个组织今后的每一次构建，看到的都是同一套字段。 2. **当某个字段确实缺失时，扩展一个默认模型。** 联系你的 iMBrace 联系人。把一个字段加进默认模型，会让它出现在每一个组织面前，而不是为单个客户单独拉出一个分支模型。 3. **只有在不存在默认模型的地方，才自己编写**，并且要用平台自身的风格来写，这样将来的默认模型才能干净利落地取代它。 ## 不要做的事 - **把模型管理当作一个独立、刻意的步骤来做，绝不要把它当成某次构建的副产品。** 在正在运行的构建之外创建或修改文档模型，这样每一个读取某类文档的构建，指向的都是同一个、唯一的模型。 - **不要把模型的选择交给运气。** 如果某一步总是读取同一类文档，就明确告诉它该用哪个模型，这样每一份文档都会落在你预期的那张数据表上。 ## 用自己的文档来验证 在一项设计开始依赖它之前，先用几份你自己的文档，逐一核查以下每一点： - **一个字段很多的模型。** 一个有几十个字段的模型，拆成几轮各有侧重的核查，会更容易验证。不管模型大小，都要把每一次结果对照字段清单逐一核查，确保每个字段都有着落。 - **嵌套行。** 发票上的明细行、简历工作经历里的各段任职：在你的测试集里确认，每一条子行都落在与其父记录相链接的那张数据表上。 - **一份其实是表格的文档**——比如一份价目表、一份对账单——它对应的是许多条记录，而不是一条。要把它当作若干行来读取。 - **一份看起来不像自己类型的文档。** 在测试集里加入一些不典型的样本——比如一份没有职责部分的职位描述、一份缺少标准标题的表单——并确保智能体会把无法识别的文档如实报告为“无法识别”，而绝不会谎报成功。 - **面向整个组织的设置。** 文档模块的模型设置是在整个组织范围内共享的。把你的构建测试时所用的设置，记录在你的测试集旁边，并且每当设置发生变化，就重新跑一遍测试集。 - **模型运行在哪里。** 由哪个模型来读取你的文档，是按安装环境、按组织分别设置的。如果个人数据必须留在本地，就要请负责这套安装的人确认：文档模块所用的每一个模型——无论用于阅读还是用于检索——都运行在这套部署内部，然后才能放入第一份真实文档。 ## 值得投入的设计选择 - **模型越少，越省成本、也越准确。** 分类时，会把每一份文档与组织里的每一个模型逐一比对，所以每一个用不上的模型，都会增加成本和出错的空间。只保留你在用的模型；如果某一步总是读取同一类文档，就让它指向那类文档对应的数据表，把模型固定下来。 - **对任何你会用来分组或制图的字段，给它一个封闭的词表。** 在字段的说明里列出所有允许的取值，这样分组和制图，用的就是一套固定、已知的术语。 - **用一份文档是什么、又不是什么，来描述每一种文档类型。** 说明里点出那些和它极为相似、但并不是它的类型，正是让不同类型彼此区分开的关键。 ==================== build-it-well/anti-patterns.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 反模式 这些做法在当下往往显得合理，这正是为什么值得提前把它们一一点名。 ## 背后空无一物的关卡 一个本该由人更新的状态字段，实际上却没有任何东西在监看它，也没有任何东西依据它的变化采取行动。**代价：** 它在评审时看起来像是有监督，但到了生产环境里却什么监督也没有——东西发出去了，却没有人真正批准过。**修复方法：** 把这个界面接到真正依赖它的东西上，并在正式宣布完成之前端到端走通整条路径，包括“还没有人做决定”这种情况在内。 ## 填在单元格里的决定 一个人被要求在数据表里编辑一个值来批准。**代价：** 那个值藏在一张他们没有理由打开的表格里，要保存后才会生效，没有一个业务人员会把它当成在做决定——于是批准来得很晚，或者根本不来。**修复方法：** 在他们本来工作的地方请他们决定：一封卡片式的邮件，按钮会打开确认页面，文档就在眼前，之后再把决定记录到那一行上。参见[人工批准](/zh-cn/learn/build-it-well/human-approval.md)。 ## 问完就挂起的请求 一个构建向人请求做决定，然后就停在那里。决定本身被记录下来了，但后续什么都没有发生：文档没有被发出去，提出请求的人也没有被告知，只能靠自己发现问题、再回来重新问一次。**代价：** 它能通过评审，却在生产环境里失效——工作被记录下来却没有完成，还得有人手动去追。**修复方法：** 设计这个请求环节，使其在得到答复后（无论是批准、驳回，还是被搁置）能够自动接着往下走，让流程自己把工作做完，或者自己报告结果。 ## 自信满满的总结 一个由 AI 生成、读起来很顺、但背后什么依据都没有的答案。**代价：** 正因为它读起来令人信服，才能在评审中蒙混过关，结果决策就建立在一个谁也无法追溯的数字上。**修复方法：** 要求每一个数字都必须带上它的出处记录；当数据中确实没有答案时，就直接说明，而不是自己编一个来填补空白。 ## 可以绕过的计算器 没有任何机制强制让运算经过一个专门的、可核查的步骤，于是在压力之下，AI 就自己把数算出来了。**代价：** 它通常是对的，而这恰恰是危险所在——出错的情况很少见、也很安静，不到有人去核查往往不会被发现。**修复方法：** 每一次都把所有运算路由到同一个专门的计算步骤，并展示所用的输入。 ## 写进提示词里的规则手册 把限额、标准或阈值直接写进 AI 的指令里，而不是作为可编辑的数据来保存。**代价：** 业务人员没有开发人员协助就没法改动一个数字，也没有人能审计某个案例究竟触发了哪一条规则。**修复方法：** 把规则作为数据保存在一条记录上，让非开发人员也能直接打开并编辑。 ## 分叉出来的副本 复制一个正常运行的构建的内部逻辑，为新的场景做出一个几乎一模一样的版本，而不是把原来的构建参数化。**代价：** 变成两样东西要维护，还会在不知不觉中彼此走样，而且下一个接手的人往往根本不知道还存在第二份副本。**修复方法：** 用参数化代替复制。如果确实需要一个真正独立的第二版本，就给它自己的名字和自己的文档，而不是让它冒充原来那一个。 ## 自建捷径 用自定义代码去做平台本来就已经内置提供的事情，通常是因为事先没有人去核实过。**代价：** 它通常需要一个原本内置方式根本不需要的凭证，而且构建一旦迁移到另一个账户就会失效。**修复方法：** 在写任何代码之前，先查一查平台当前的能力清单。参见[原生优先](/zh-cn/learn/build-it-well/native-first.md)。 ## 未经核查的提取 不经核对就直接信任一次提取的结果，而不去对照当初要求提取的内容。**代价：** 如果没有人拿输出结果去对照字段清单，漏掉的字段很容易被忽略。**修复方法：** 把每一次提取结果都对照字段清单逐一核查，并把过长的字段清单拆成几轮各有侧重的提取。 ## 用检索来数数 把计数或引证类问题——“有多少个”“哪份文档在第几页提到”——当成搜索问题来处理。**代价：** 这类问题需要结构化记录才能给出精确答案；单靠检索没法展示它的推导过程。**修复方法：** 把材料索引成结构化记录，再对其进行查询。把搜索检索留给真正的“我该怎么做”这类问题。 ## 抢跑触发 一个流程对一连串相关活动中的第一项就立刻做出反应，而不是等这一连串活动告一段落。**代价：** 结果在其余相关项目到达之前就已经生成，一旦其余项目到达，它当场就变得错误或不完整。**修复方法：** 等这一连串活动平静下来之后，再针对完整情况一次性采取行动。 ## 轻信的关卡 一个审批环节直接读取 AI 刚刚给出的数字，而不是根据底层记录独立算一遍。**代价：** 一个错误的数字可以自己批准自己，因为从来没有人拿它去对照过原始来源核实。**修复方法：** 这个关卡必须每次都自己重新推导出答案。 ## 自我汇报 一个构建自己汇报自己的成功——一段看起来煞有介事的粘贴结果，一个“已完成”或“已上线”的状态，而实际上从来没有人真正看着它运行过。**代价：** 对一个从未被真正观察到的世界状态抱有信心。**修复方法：** 亲自运行一遍，亲眼看着它发生，只有在真正有人看到它成功运行之后，才能把它标记为可用。 ## 绕开隐私保护的捷径 为了回答一个棘手的问题，临时把一处存放原始敏感数据的存储直接连接给 AI。**代价：** 敏感数据与 AI 之间的隔离，本来就是整个隐私保障的全部内容，而这一刻，它已经在悄无声息中不再成立了——哪怕只是短短一瞬间。**修复方法：** 绝不连接，哪怕只是暂时的也不行。如果一个问题确实需要用到原始数据，那这个问题本就不该由那个 AI 来回答。 ## 写进提示词里的标准答案 把预期答案——也就是演示应该展示出来的那些数字——直接写进智能体自己的指令里。**代价：** 演示能通过，但背后的工具其实是错的，而且要等到真正有人提出问题时才会被发现。**修复方法：** 预期数值只应存在于测试集中，绝不能出现在指令里；在智能体上线之前进行一次检查，一旦指令中包含这些数值就予以拒绝。 ## 把记忆当成数据来源 一个智能体靠自己记得的内容、或者靠此前某个时间点附加给它的文档来回答一个实时数据问题，而不是去读取眼前的原始来源。**代价：** 一个语气自信、却装着过时数字的答案。**修复方法：** 不要给任何依据实时数据作答的智能体附加文档，给它定一条常设规则——绝不把数字存进记忆，也绝不凭记忆作答，并且保留一道能够识破过时答案的测试问题。对于任何需要维持一段对话的智能体，要保留它自己的对话历史——它需要靠这段历史，才能对自己先前说过的话保持一致。 ## 在有争议的数字上让步 某个人提出自己的一个数字，智能体就放弃了自己原本用工具算出来的正确数字，转而附和对方。**代价：** 答案变成了对话中语气最自信的那个人说了算。**修复方法：** 给智能体定一条质询规则——重新跑一遍工具、尝试用工具复现对方给出的数字，并清楚说明每个数字各自代表什么。 ## 透视表快照 把一份转换过格式的表格里的数据透视表当成仍在实时计算来读取。当一个 Excel 工作簿被转换成 Google 表格时，其中的数据透视表会保留转换那一刻显示的数值，之后就不再更新。**代价：** 从透视表里取出的每一个数字，都被冻结在转换发生的那一天，无论底下的原始行数据有多新。**修复方法：** 从原始行数据重新计算，并且无论在哪里展示这份透视表，都要注明这一点。 ## 整张表甩进一轮对话 在一轮对话里，把一整张大型表格或数据表原封不动地丢给智能体。**代价：** 这超出了智能体一次能消化的量，之后的一切都建立在一次看似完整、实则只读了一部分的基础上。**修复方法：** 用平台自带的读取步骤来读取它，用一个计算步骤汇总它，只把算好的最终数字交给智能体，并附上这些数字所依据的行、筛选条件和日期。参见[原生优先](/zh-cn/learn/build-it-well/native-first.md)。 ## 从未被复用的共享部件 因为看起来“应该会有用”而构建出来的东西，实际上却从来没有被真正复用过，却还要一直维护下去。**代价：** 持续投入维护成本却换不回任何价值，还会让人误以为这个构建比实际情况更模块化。**修复方法：** 在至少有两个真实、独立、且叫得出名字的需求出现之前，不要把某样东西标注为“可复用”。 ==================== build-it-well/review-checklist.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 审查清单 这就是内部一直在用的那套审查，这里把它写成你可以自己拿来对自己的构建使用的版本。完成一次大约需要一个小时；如果执行审查的人，不是这个构建的开发者，效果会好得多。 ## 如何进行这项审查 1. 把下面的评分表复制一份，放在你正在审查的构建旁边。 2. 逐条过一遍每项原则下的问题，这些问题取自[八项原则](/zh-cn/learn/build-it-well/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 模型会读取这个构建的数据，其中是否有任何一个在部署范围之外？ | | | | ## 已接受的差距 | 差距 | 为什么目前可以接受 | 接受人 | 日期 | 何时重新审视 | |---|---|---|---|---| | | | | | |