automation-architecture

自动化架构

目标

将客户用例转化为精确、最精简的 Nexor 配置：为各个原语命名，填写具体字段值，并将它们端到端连接起来。交付成果是配置，而非建议。

分解三定律

选择任何原语之前，先应用以下定律。它们不是风格偏好：每条都定义了平台唯一能够门控、触发、模板化或验证的结构。即使演示效果正确，违反其中任何一条的设计也不可靠，因为平台无法识别以文字描述存在的部分。

定律 1——系统所需的每条信息都必须是变量

如果构建依赖于某项信息，就必须将其设为命名的工作流字段或 lead metadata。绝不能只将它写在提示词中，也不能指望“Agent 会从对话中记住”。

• Agent 必须获取的信息 → 工作流字段，设置 required: true，并提供 extraction_hints。
• 外部工具（CRM、表单或客户自己的后端）提供 lead 身份／联系信息 → 通过标准 lead 创建／更新约定写入 first_name、last_name、email 和 phone。绝不能将这些值隐藏在 metadata 中；metadata 不会更改 Nexor 的联系人目标地址。
• 外部工具提供其他上下文信息 → 直接放入 lead 的 metadata JSON 对象中。键可以存放字符串、数字、布尔值、null、数组或嵌套对象；完整的 metadata 对象会注入下一个运行时 Agent 提示词，因此 Agent 无需为每个键设置单独字段，就能访问每个参数和值。
• Agent 必须询问、验证、规范化外部提供的信息，或以此为门控条件 → 添加带有 metadata_key 的工作流字段（必要时还要添加 intake_value_map），这样 metadata 会预填字段，而无需再询问。metadata_key、options、extraction_hints 和 validation 只能在初始的 create_workflow 调用中写入——update_workflow_structure 仅接受 key、label、type、required、sort_order。创建 Agent 前，先完成变量清单。
• 工具生成的信息 → 使用 llm_response_fields 将其保留在本轮对话中；如果后续步骤需要，则由后置工具钩子将其写入 metadata。
• 门控条件仅读取字段。required_field_keys、requires_all_fields 和 transition_rules 无法读取 metadata。
• **确定性发送器仅读取 metadata。**状态自动化的 args_template、webhook 的 payload_template 和 HTTP 工具模板会读取 {{lead.<path>}} / {{lead.metadata.<key>}}，无法读取已收集的字段值。自动化必须传输的任何内容，都必须在 lead 到达触发状态之前镜像到 metadata 中（通过后置工具钩子或 patch_metadata）。完整的读取器／存储位置矩阵见 references/configuration-reference.md。

对于设计中使用的每条信息，都要注明其键和存储位置。若某条信息只存在于对话历史中，就无法用于门控状态、路由 lead、填充请求正文或筛选任务。

Law 2 — Agent 内部的每次状态变化都是一个状态

如果 Agent 的行为、权限或义务在某个时刻发生变化，那么该时刻就是 Agent 工作流中的一个状态。绝不能将其描述为提示词中的“阶段”，也不能将其作为布尔值存放在元数据中。

状态是平台其余部分唯一可以操作的对象。不是状态的阶段，对 workflow_tools.available_in_statuses、status_automations.on_status_key、基于 to_status.key 的 webhook 筛选器、timeout_config、transition_rules / required_field_keys、后台任务的 workflow_filters.status_keys、再联系的 trigger_status_key 以及 assignment_config 都不可见。

为每个阶段设置 key、label、entry_hint（根据 Law 1 变量说明进入条件），以及明确的门槛。当字段值足以完全决定下一步时，添加 transition_rules.rule_groups 并设置 auto_evaluate: true，让平台推进潜在客户，而不是依赖 Agent 调用 set_lead_status。

每个门槛都要通过 required_field_keys（或 requires_all_fields）加上 transition_rules 来表示。无法通过 MCP 写入 variable_refs——它只是仪表板的显示提示，因此依赖它的设计根本没有设置门槛。review_agent_system_plan 会替你执行此规则：任何既没有 entry_hint 也没有 transition_rules 的非初始状态，都会返回一个澄清问题。

重新排序现有工作流时，必须完整保留其语义核心：Lead created (core_new)、Contacted (core_contacted) 和 Engaged (core_engaged) 始终依次位列第一、第二、第三。调用 get_workflow，将其余每个已持久化的状态 key 原样传递给 reorder_workflow_statuses，然后再次调用 get_workflow，并在报告成功前比较完整顺序。绝不能通过发送原始 sort_order 值来重新排序、添加虚构的 Discarded 列，或根据可编辑标签推断核心状态。有关分组行为，请阅读 references/configuration-reference.md；有关写入约定，请阅读 references/mcp-tool-surface.md。

规则 3 — 每次 Agent 身份切换都发生在一个会移交的边界状态

改变语气、角色、目标、提示词内容、工具集、渠道组合或联系频率，意味着这是一个不同的 Agent。切换绝不会在提示词内部进行，而是通过线索退出的边界状态完成：

• 终止式移交（默认）： is_terminal: true 加上 transfer_config: { "target_workflow_id": "<real id>" }。这是唯一会自动触发移交的形式。每条 Agent 路径都会先检查 is_terminal，再读取 transfer_config，所以非终止状态即使带有 transfer_config 也不会触发移交——该配置会被正常保存，但不会产生任何效果。
• 边界状态绝不可命名为 future_*、contact_later 或 colder。 这些键会被视为软终止状态，并在读取 transfer_config 之前从终止状态副作用路径中排除，因此即使状态正确标记为终止状态，移交也会被跳过。这是整个系统中最隐蔽的故障。
• 暂停边界： 在系统外执行移交时，使用 pause_bot: true，例如通过后台任务的 workflow_transfer / force_transfer 操作、一次性移交 API 或人工操作。暂停边界必须指定执行者，否则线索会永远保持静默。这种做法是安全的：pause_bot 是一个状态标记，不会设置 workflow_runs.is_paused，因此使用标准 exclusions.skip_paused: true 的任务仍会处理这些线索。

无论采用哪种形式，源 Agent 的所有权都会在边界处结束：每条线索恰好只有一个 Agent 处于活动状态。目标 Agent 始终从自己的初始状态开始，重新启动其联系节奏，而源 Agent 收集的字段则会作为只读的移交链快照一同传递。

禁止的形式：提示词中写着“满足条件后，切换为成交语气”；以更改 Agent 角色为目的的工具；同一条线索上有两个 Agent 同时处于活动状态；移交目标指向目标 Agent 内部的某个特定状态。

规则 2 还是规则 3？

目标相同、角色相同、工具集相同、联系节奏相同，只是对线索的了解更多 → 状态。目标、提示词、工具、渠道或联系频率不同 → 通过边界状态进入新模式。~80% 测试只在同一个意图内进行：两个候选模式具有相同意图和表达风格，且提示词、工具和日程约有 ~80% 相同，则合并为一个具有更多状态的模式。它绝不会合并两个不同的意图。

默认方案：按意图拆分为 2–3 种模式

运营人员看到并命名的是智能体（主工作流）。你在其中构建的是模式（工作流）：每种意图对应一种模式。默认应拆分，而不是编写一个宽泛的提示词。除非运营人员明确且毫不含糊地表示他们只想要一种模式（“我绝对只想要一种模式”），否则应进行拆分：

• 意图变化时创建新模式——也就是对话希望引导线索采取的行动：销售、跟进、提供折扣、预约、收款、留存。
• 沟通风格变化时创建新模式——即使在“同一笔销售”中，语气、强度、节奏、人设或渠道组合发生变化，也应创建新模式：热情且提供信息的开场、坚持不懈的提醒，以及单次让步，属于三种不同的沟通风格。
• 典型需求拆分为 2–3 种模式。“在我们的电商平台销售门票，并通过折扣进行跟进”应拆分为两到三种模式（销售 → 跟进未付款用户 → 提供折扣），而不是一种或五种。references/recipes.md 中的配方 25 展示了完整流程。
• 仅在明确要求时使用一种模式。 在 plan.decomposition 中引用运营人员的原话，设置 single_mode_explicitly_requested: true 和 operator_instruction；如果缺少这些内容，review_agent_system_plan 会阻止单模式方案。
• 绝不超过 5 种。 超过四种模式会割裂一段对话（每次切换都会重置节奏并重新触发首次联系）；除非 large_system_explicitly_requested 包含运营人员的原话，否则审核会阻止该方案。合并意图和沟通风格都相同的模式。
• 确保每种模式都可到达。 列出的第一种模式是入口点（或将其他模式标记为 entry_point: true）；每种其他模式都必须是某种模式的终止转接目标，否则审核会询问线索如何到达该模式。

describe_agent_configuration 会通过 mode_split 返回这项约定；在方案中说明每种模式的意图和沟通风格，并向运营人员复述审核给出的 decomposition 摘要。

基础机制

客户提出的需求都归入以下一项或多项：

#	基础机制	触发条件	需要编写代码？	范围
1	Agent 配置（状态 + 接入字段）	潜在客户发送消息，或对话进行中	否	单个潜在客户，当前轮次内
2	工作流 HTTP/MCP 工具	Agent 在当前轮次中需要外部信息或执行操作	否	单个潜在客户，同步执行
3	规则（提醒 / 主持人通知 / 重新联系）	会议生命周期、长时间无活动	否	单个潜在客户
4	出站 Webhook	平台事件（状态变更、会议生命周期）	否	通知外部 API（CRM、ERP、自有后端），每次发生事件时通知
5	状态自动化	潜在客户达到特定状态	否	调用一个 HTTP/MCP 工具，每个潜在客户恰好一次
6	后台任务	cron 或标签事件	否	经过筛选的群组，使用声明式步骤
7	云函数	lead.* / workflow.* / meeting.* 事件	JS	每个事件对应一个潜在客户
8	定时函数	Cron + 时区	JS	根据查询获取群组
9	工作流转接	终止状态，且带有 transfer_config	否	单个潜在客户，Agent 之间交接
10	接入 API / 入站 Webhook	外部工具（CRM、表单、Zapier、自有后端）推送潜在客户	否	创建潜在客户 + 纳入工作流
11	节奏配置（联系时段 + 每日配置）	外联排期：时间窗口、各渠道的联系频率、热点联系	否	工作流的整个出站计划
12	知识库分配	Agent 运行时需要选定的账户自有知识	否	精确指定每个 Agent 的子集，并按检索优先级排序
13	执行前钩子（带有 mode: "on_entry" 的工具）	潜在客户进入工作流，在 Agent 发送第一条消息之前	否	单个潜在客户，确定性执行，不能按阶段设置门槛
14	预处理器	入站潜在客户到达，在任何 Agent 接手之前	否	按顺序执行条件规则，选择入口工作流
15	阶段超时（timeout_config）	潜在客户进入某个状态后经过一段时间（“48 小时未回复”）	否	单个潜在客户；将其移至同一 Agent 的另一个状态——这是平台唯一的延迟机制。若目标为带有 transfer_config 的终止状态，则会延迟交接

决策阶梯——配置优先于代码

配置对运营人员可见，可在 UI 中编辑，且不会导致崩溃；代码对运营人员不可见，而且需要你永久维护。按从上到下的顺序检查阶梯，在第一个能满足需求的层级停止。

1. 原生对话配置能否表达？ 状态、收集字段、提示词规则或确定性分支 → Agent 配置。“询问 X 并根据回答分支”属于状态和字段，而非代码。第 1 条和第 2 条通常已将大部分需求归入这一层。
2. 这是等待吗？“如果他们 N 小时内没有回复……”“3 天后将他们移至……”“48 小时后转交给跟进 Agent” → 在等待状态上配置 timeout_config（使用 set_status_timeout_rule，或在 create_workflow / update_workflow_status 中内联配置），并指向下一个状态——或者指向一个带有 transfer_config 的终止状态，以实现延迟转交。多步等待时使用状态链；计时从进入状态时开始，收到回复不会重置计时。这对应控制面板中的“如果潜在客户未回复 → N 小时后 → 移至”控件。对于单个潜在客户的等待，计划函数、后台作业、云函数或重新联系 on_exhausted 绝不是正确方案（配方 23）。
3. 这是标准的生命周期提醒吗？ 预约确认、会前提醒、通知主持人、重新联系长期未跟进的潜在客户 → 使用规则。配置好后即可停止。
4. 状态变化能否准确定义触发时机？ 优先选择确定性执行，而非让模型决定是否调用工具。状态变更 → 如果接收方能根据事件采取行动，则使用筛选后的出站 Webhook；如果需要 Nexor 调用配置好的端点一次并发送自定义请求体，则使用状态自动化。字段／变量或其他潜在客户事件 → 触发云函数（information.collected、information.updated、lead.updated，或支持范围最窄的事件），并通过相关键／变更进行限制。
5. 结果是否必须在 Agent 发送首条消息之前就绪？ → 使用预执行钩子：set_workflow_tool_execution({ mode: "on_entry" })。潜在客户进入工作流时，平台会立即运行工具，在 Agent 发言前完成，且无需模型作出决定。这适用于信息补全、资格查询和账户上下文，也适用于需要在转交目标处就绪的数据。此模式不能按阶段进行限制（两种模式互斥），因此只有在“进入时”确实是合适时机时才使用。
6. 如果没有状态事件能先行触发，Agent 是否确实需要外部结果才能继续当前轮对话？ 将客户端端点作为工作流 HTTP／MCP 工具，以 mode: "agent_decides" 暴露。这是可靠性最低的一层，因为必须由模型选择并调用工具。将特定于客户端的逻辑保留在客户端系统中，收紧接口范围，并在工具仅适用于某个阶段之后（例如 qualified）时，通过 available_in_statuses 限制其可用状态。
7. 这是“筛选潜在客户 → 判断条件 → 执行动作”吗？ → 使用带声明式步骤和操作的后台作业。始终设置 max_leads_per_cycle 和 cooldown_minutes；凡是会向真人发送消息的操作，都先进行试运行。
8. 异步工作是否需要作业所用词汇无法表达的自定义逻辑或外部 API？ 根据触发语义选择：“当某个潜在客户……” → 云函数（事件，单个潜在客户）。“每天早上／每周一……” → 计划函数（Cron，潜在客户群体）。如果某个“当”触发可容忍数小时延迟，且涉及多个潜在客户 → 优先使用计划扫描（其试运行会先显示整个群体）。如果“当”仅表示在某个阶段经过一段时间，则属于第 2 层，而非这一层。
9. 潜在客户是否需要完全不同的对话方式或触达频率？ 目标、角色设定、节奏、渠道组合或工具集发生变化 → 从边界状态转交到其他工作流（第 3 条）。资格判定 Agent 可以通过 qualified_now 和 qualified_later 等终止状态分流，每个状态都配置自己的 transfer_config；接收工作流分别负责高频销售或低频培育。如果只提出“培育”需求，默认应采用独立的低频、仅限电子邮件工作流，大约每 2-4 周联系一次——绝不能仅仅放慢销售节奏，也不能让同一个 Agent 使用更多渠道。如果两个目标的意图和语气相同，且提示词、工具和日程有 80% 相同，则保留一种模式并增加状态；但绝不能将两种不同意图合并到一个提示词中：默认结构为 2–3 种模式（见上文“默认结构”）。

集成指南

当需求涉及集成——在 Nexor 与外部工具（CRM、ERP 或客户自己的后端）之间传输数据时，应根据方向和频率选择合适的原语。Functions 是最灵活的方式：可编辑的 JavaScript，并提供 axios，因此可以双向访问任何外部 API。

Nexor API 的标准来源

当配置、示例或客户集成需要直接调用 Nexor 时，请使用以下确切的 API 来源：

环境	API 来源
Staging	https://api-staging.getnexor.ai
Production	https://api.getnexor.ai

在来源后附加文档中列出的路由，例如 /api/public/leads。请勿替换为仪表板来源、MCP 来源、staging-api.getnexor.ai 或旧版 onrender.com 后端。凭证和 API 来源必须属于同一环境；执行任何会产生副作用的调用前，先确定目标环境，不要默默选择 Production。

这些来源适用于确实需要调用 Nexor 的集成。它们不是 Nexor Functions 内部的默认数据路径。应优先使用运行时原生访问方式：

• 在事件 Cloud Function 中，从 ctx.lead 或 lead 读取触发事件的潜在客户；切勿通过 /api/public/leads 重新获取。
• 在 Scheduled Function 中，将 get/list/search/filter-leads 需求转换为 lookup_config，预览该人群，并在代码中使用已解析的 ctx.leads 数组。不要为同一人群查询 /api/public/leads。Leads 没有 workflow_id 列：当前 Agent/工作流范围应在支持关系查询的查询中使用 workflow_runs.workflow_id = <id> 和 workflow_runs.is_active = true 这一对条件。
• 对 Nexor 支持的变更操作，使用 updateLead / updateMetadata 和 effects.*。只有在确实需要执行不受支持的原子操作时，才直接调用 Nexor API，例如在同一次运行中需要新 ID 时，同时执行 create/upsert、工作流注册和首次联系；不要为了重复读取而调用。

选择接口前先明确同步方向

在方向明确之前，不要把“同步这些信息”视为完整需求。提出建议或配置任何内容前，先确定数据是流入 Nexor还是流出 Nexor。如果请求未明确方向，请列出这两个互斥选项并等待答复；不要根据“同步”一词猜测。

对于流入 Nexor的数据，映射前先对每个传入键进行分类：

• 将线索身份信息和联系信息放入标准线索列：first_name、last_name、email 和 phone。通过常规的线索创建/更新契约更新这些字段，绝不要通过元数据更新。元数据不会改变 Nexor 用来联系线索的地址或号码。
• 将 Agent 应了解的所有其他可复用客户信息放入 lead.metadata。创建/更新插入时使用 metadata 对象，或通过 PATCH/PUT /api/public/leads/:id 对其进行浅合并；批量合并请使用 PATCH /api/public/leads/metadata。下次 Agent 执行时会加载完整的元数据对象，因此现在写入的值会在下一轮/次运行中可用，无需将其复制到提示词正文中。
• 仅当同一个值必须预填 intake 问题或参与仅基于字段的状态门控时，才添加带有 metadata_key 的工作流字段。元数据仍是入站上下文的来源；字段则是结构性桥梁。

对于流出 Nexor的数据，请根据下表选择出站触发方式。元数据可以作为载荷中包含的源值，但写入元数据并不是出站同步机制，本身不会发送任何内容。

方向	频率	用途	原因
Nexor → 外部	状态变更	出站 Webhook 或状态自动化	平台状态可确定性地触发；不依赖模型决定选择哪个工具
Nexor → 外部	字段/变量或线索事件	云函数	事件可确定性地触发；自定义代码可以检查发生变更的键并调用任意端点
Nexor ↔ 外部	在 Agent 轮次期间，没有可用的状态触发器	工作流 HTTP/MCP 工具	仅在 Agent 需要立即获得响应时使用；客户端的端点仍是事实来源，但由模型选择调用的可靠性较低
Nexor → 外部	批量	定时函数扫描	使用 ctx.leads[] 中的群组，按线索分别推送或聚合后推送
外部 → Nexor	推送（对方调用你）	公共线索 API / 入站钩子	一次请求即可完成更新插入、元数据写入和加入工作流，无需编写代码
外部 → Nexor	拉取（Nexor 调用对方）	定时函数	使用 Supabase 风格的链式筛选器查询整个线索对象，通过 axios 调用外部 API，然后通过 effects 或公共 API 使用自定义元数据创建/编辑线索
外部 → Nexor	结果在其他地方发生（已付款、已签署、已激活）	转化事件：POST /api/public/conversions，附带线索标识符（+ amount、currency、description、metadata）	确定性触发；Nexor 会将线索转到该类型所配置的 Agent/状态、Agent 或其群组

若能表达所需时机，应优先采用确定性机制：规则、Webhook、状态自动化和事件触发的云函数都不依赖模型记得或决定调用工具。若客户端的端点已经负责其轮询分配、CRM 归属、定价或资格判定逻辑，就不要将这些逻辑复制到提示词或函数中。仅当当前对话确实需要 Agent 可调用工具的响应才能继续时，才使用这类工具。

客户端负责的能力与确定性执行

将客户端的端点视为能力所在之处，将 Nexor 视为编排器：

1. 确定状态、字段、变量、潜在客户、会议或工作流事件是否定义了执行时机。如果是，则将该事件接入 webhook、状态自动化或云函数；不要要求 Agent 调用端点。
2. 将权威业务决策保留在端点中。Nexor 传递事实；Agent 和函数都不应重复客户端的算法。
3. 只有当 Agent 必须在当前轮次内获取结果，且确定性触发无法先行执行时，才使用对话式 HTTP/MCP 工具。
4. 对其余可由 Agent 调用的工具，将 available_in_statuses 设为准确的有效状态键。将 qualified 门槛与 requires_all_fields / required_field_keys 配合使用，确保资格审核完成前无法查询可用时间或预约。
5. 对每次工作流运行中必须执行一次的不可逆对话操作，使用 call_once；对可能需要合理刷新只读工具，则关闭此选项。
6. 定义成功、失败、持久化和重试行为。调用失败后，绝不能让 Agent 编造负责人、时间段、价格或外部结果。

请阅读 references/configuration-reference.md 中关于工作流工具和阶段门控的约定；如果请求与销售代表分配类似，请使用 references/recipes.md 中的轮询映射。

会议主持人选择

会议主持人选择决定了由预约 Agent 所分配的哪位高管提供向潜在客户展示的时间段。这不涉及潜在客户归属、销售管道分配或外部 CRM 轮询。

1. 在提出更改前，针对确切的工作流调用 list_meeting_types 和 list_executives。Agent 必须且只能使用一个现有会议类型。如果存在多个会议类型，则停止操作并帮助操作人员将其合并为一个；绝不要创建或悄悄选择另一个类型。
2. 将零位或一位已分配高管视为无需进行路由决策。若有两位或更多高管且没有选择标准，请说明可用时间段会通过轮询平均分配。添加第二位高管后，主动询问对方希望采用默认方式还是明确的主持人选择规则。
3. 仅根据预约 Agent 实际可知的事实构建规则：标准潜在客户属性、潜在客户元数据或 get_workflow 返回的工作流字段。通过 list_executives 返回的 user_id 引用已分配的高管。如果规则中提到未知或未分配的人员，应先与操作人员解决这一不匹配（invite_user，然后 add_executive），再进行任何写入。
4. 根据必须满足的条件选择层级。由字段驱动或加权拆分（“renta 超过 50000 分配给 Ana，其余在 Bruno 和 Carla 之间按 2:1 分配，不符合条件者取消资格”；“严格交替”）应通过 set_meeting_type_routing({ workflow_id, agent_selection_rules }) 强制执行 — 使用 field 和 min 指定层级、用 agents（用户 ID）指定人员、用 mode 指定 round_robin / cycle、并配置 weights、pattern 和 action: "disqualify"；该规则会在提供选项和预约时应用。以文字表达的软性偏好应通过 update_meeting_type 设置 agent_selection_criteria：保持简短且有序，绝不要声称此规则由服务端强制执行 — 预约 Agent 会在选择返回的时间段时读取该字段。
5. 读取规则或条件（list_meeting_types / set_meeting_type_routing 响应）并逐项核对。只有在同一会议类型中确认包含请求的值后，才报告成功；否则应说明不匹配，不要暗示路由已更改。

不要使用旧版会议选择工具、直接访问数据库，也不要通过第二种会议类型来表达路由。如果由客户端自己的端点决定主持人，请改用 set_host_assigner — 参见 references/booking-agent.md。

预约 Agent

创建预约 Agent 时，它尚不可预约。在 set_workflow_active 生成能够提供时段的 Agent 之前，必须按依赖顺序满足六项前置条件；get_account_readiness 会将每项缺失条件报告为预约阻塞项，并列出解决它们的工具。完整的参数约定见 references/booking-agent.md；顺序如下：

1. create_workflow({ goal_type: "appointment", timezone, … }) — 显式传入 IANA timezone：所有提供的时段都以此时区为基准显示。三个核心阶段和虚拟的 Discarded 列始终存在；请在它们之后设计预约阶段。
2. create_meeting_type({ workflow_id, name, duration_minutes, location_type }) — 或复用 list_meeting_types 返回的唯一类型。一个工作流对应一种会议类型；location_type: "in_person" 需要提供 location_details。创建后即为 active；有可用时间的主持人就绪后即可预约。
3. 为每位负责主持会议的人员调用 add_executive({ workflow_id, user_id })（通过 list_team 获取 id；不在团队中的人员需先调用 invite_user）。仅有一位符合条件的成员时 → auto_assign_solo_host。
4. set_host_schedule({ user_id, timezone, slots: [{ weekday, start, end }] }) — 提供完整的每周日程，时区使用主持人的时区；休假日使用 set_host_blocks。
5. connect_calendar({ user_id, provider: "google" | "outlook" }) → 返回 connect_url，只能由主持人在浏览器中完成连接。发送该链接，说明谁必须打开它，并轮询 get_calendar_connections({ user_id })，直到 status: "active"。轮询确认前，绝不可报告日历已连接。Calendly 可替代步骤 4–5（connect_calendly → map_calendly_hosts → set_calendly_binding）。
6. get_reminder_catalog({ workflow_id })，然后对每条规则调用 set_reminder_rule，并提供完整参数约定 — trigger_event（event_created、event_cancelled、call_analyzed、event_enrolled；不存在重新安排的触发事件，新的时间会再次触发 event_created）、channel（只能使用该目录标记为此账户可用的渠道）、template_name（已批准的 WhatsApp 模板，或 retell / sms / email 的变体键）、有符号的 delay_minutes、delay_reference trigger 或 event_start。set_host_reminder_rule 仅支持电子邮件，且仅在 event_created 时触发。
7. 有两位或更多主持人时，调用 set_meeting_type_routing（参见上文“会议主持人选择”）。
8. review_agent_system_plan({ plan }) — 预约 Agent 必须包含 meeting_type、hosts[] 和 calendar_plan（或 booking_provider）；缺少这些内容的预约计划会被拒绝。每次执行步骤 1–7 中的变更之前，都必须先对摘要计划（“看起来可以吗？请告诉我，我会着手构建。”）表示同意。
9. 读取所有配置并核实 — get_account_readiness 显示没有预约阻塞项，且 get_workflow_slots 返回时段 — 然后调用 set_workflow_active，并单独确认。

之后操作 Agent 属于不同的工具系列：使用 list_meetings / get_meeting_stats 查看预约，使用 book_meeting / reschedule_meeting / change_meeting_host / cancel_meeting 进行运营人员驱动的变更（每项操作在未设置 confirm: true 时都会先预览），使用 set_meeting_status({ status: "no_show" | "completed" }) 记录结果。**get_available_slots、confirm_and_book、create_event、reschedule_event、cancel_event、request_channel_swap 和 schedule_followup 是 Agent 在对话过程中使用的运行时工具 — 不能通过 MCP 调用。**它们只会作为配置中的名称出现，用于设置阶段门控或为外部预约者停用这些工具。 当客户端自己的端点拥有日历时，set_external_booking 需要四种操作全部齐备——slots、create（tool）、reschedule_tool、cancel_tool，因为缺少某种操作时，系统会静默地不再同步：出现虚假会议，提醒仍会持续触发。唯一的例外是，运营人员在对话中以书面形式明确接受这一限制；请将这句话记录在规范中。参见 references/booking-agent.md。

工作流

1. 将需求重述为触发条件 → 条件 → 操作，并在选择配置界面前先确定同步方向是流入 Nexor / 流出 Nexor，再将时机分类为轮次内 / 事件 / 批处理 / 入站，并区分 Agent 必须询问的内容（接入字段）、客户系统发送的内容（标准线索身份列与元数据），以及必须执行的操作（工具调用或自动化）。
2. 选择任何原语前，先应用三条法则起草骨架：将设计所需的每项事实列为带名称的变量，并注明其存储位置和读取者（法则 1）；将每个 Agent 内部阶段列为状态键，并注明其进入标准和门控条件（法则 2）；将每次身份切换列为边界状态，并注明其形态、目标 Agent，以及——对于暂停边界——其执行者（法则 3）。然后确定系统规模：每个意图和每个寄存器各一种模式，默认 2–3 种模式；仅当操作人员明确要求恰好一种模式时才使用单一模式；绝不使用 5 种或更多模式（参见“默认结构”）。凡无法归入这三份清单的内容，都还没有设计完成；先将其列入，再继续。
3. 在提出任何非平凡或多 Agent 构建方案之前，调用 describe_agent_configuration，并通过 list_workflows / get_workflow / list_workflow_tools / list_webhooks 读取当前状态。平台提供了自身要求的流程和界面映射；应遵循该映射，而不是依赖记忆中的映射。编辑的 Agent 若属于 Agent 组（master_workflow_id），默认读取单位是整个组：其同级 Agent、流入和流出被编辑 Agent 的状态，以及共享的渠道绑定；绝不能只读取这一个 Agent。
4. 沿阶梯逐级推进。注明跳过的每一级及原因——这部分推理也属于交付内容。
5. 优先使用确定性的状态触发器。状态变更优先选择 webhook/状态自动化；字段/变量或其他线索事件优先选择云函数。只有当 Agent 必须在继续前收到结果时，才使用轮次内工具，并将其限制在有效状态范围内。
6. 阅读 references/recipes.md，从最接近的已完成映射开始；阅读 references/configuration-reference.md，补全所选原语的确切字段名称和值；首次写入前阅读 references/mcp-tool-surface.md。
7. 规划前先读取账户信息：调用 get_account_readiness，以及 list_whatsapp_numbers、list_email_senders 和 list_phone_numbers（若 Agent 需要预约，还需对 calendars[] / booking_providers[] 调用 get_integration_status）。将 sms_enabled: true 的活跃电话号码行视为短信渠道。账户事实是证据，不是澄清问题：绝不询问客户是否已经有 WhatsApp 号码、邮件发件人、呼叫号码、短信渠道或已保存的时区。**任何 Agent 都不得询问渠道和联系时段——也不得将它们混入其他问题中。**创建 Agent 时，它会自动获得账户中每种有已验证资源的渠道（get_account_readiness.inventory.channels）；在 create_workflow 时，每种模式都会继承所属 Agent 的渠道、联系时段和人物名称（见第 10 步）。规划模式时不要包含 channels 键（命名渠道只能作为意图写入描述和提示词，绝不能作为绑定或问题），并根据操作人员已提供的信息确定 contact_schedule；若没有提示，则采用周一至周五 09:00–18:00 的默认时段，并在摘要中用一行说明 Agent 创建时获得了什么。review_agent_system_plan 绝不会询问要启用哪些渠道，并会返回 birth_defaults（每个新 Agent 都会获得的渠道）。只有当操作人员明确要求此模式使用特定资源或更窄的渠道组合，或者 create_workflow 报告了 channel_bindings 结果而需要修复时，才运行第 8 步的资源流程。
8. 仅在操作人员明确要求时（指定某个号码或发件人、为某个模式指定更窄的渠道组合，或 create_workflow 结果报告 owned_by_other_agent / channel_binding_failed）：为该 Agent 编写预期渠道清单：注明启用的渠道，并列出 WhatsApp、邮件、呼叫和短信各自选定的确切资源 ID。注明每项资源的当前所有者。邮件发件人可共享；一个 WhatsApp 号码只能有一个直接所有者，一个呼叫号码只能有一个 workflow_id，一条短信路由只能有一个 sms_workflow_id。呼叫和短信可以合法地将同一个实际号码路由到不同 Agent。在进行任何变更前，先解决整个计划中的重复独占声明。对于真正需要配置的渠道（WhatsApp、邮件、呼叫）：如果恰好只有一个可用资源，则提供该已观察到的资源，或配置新资源的选项；如果有多个资源，则在有限选项选择器中列出所有已观察到的资源，并提供配置新资源的路径；如果没有资源，则说明情况，并提供配置资源或在没有该渠道的情况下继续的选项。短信不属于上述需要配置的渠道——短信不是“设置”出来的，而是在账户已有的电话号码上按 Agent 激活。只要存在活跃的 Twilio 号码，就不要启动购买号码流程：唯一需要确认的问题是哪些 Agent 应接收短信，然后使用 set_number_sms({ number_id, enabled: true, sms_workflow_id }) 激活。短信必须使用 Twilio 运营商号码（Telnyx 号码不支持短信）；没有国家/地区限制。只有账户完全没有电话号码时，短信配置才进入对话，并转为与呼叫相同的号码设置流程。绝不要把这些有限选项变成开放式文本问题。
9. 在进行任何变更前，使用 review_agent_system_plan({ plan }) 预检整个系统，并通过计划本地 Agent 引用之间的 transfer_to_agent_ref 表达交接，每种模式对应一个计划 Agent。除非 plan.decomposition 包含 single_mode_explicitly_requested: true 和操作人员的原话 operator_instruction，否则单模式计划会被阻止；除非 large_system_explicitly_requested 包含相应内容，否则 5 种或更多模式会被阻止；若某模式没有任何流入交接，则会触发澄清问题，除非该模式为 entry_point: true。解决所有 blocking_issue 和 clarification_question，直到 ready_for_signoff 为 true，然后展示返回的摘要并原样询问 signoff_prompt 中的问题。在用户批准 plan_fingerprint 前，不得调用任何创建/更新/运行工具。
10. 始终先创建 Agent，再创建其模式。 每个工作流都是 Agent（主工作流）内部的一种模式；工作流绝不能独立存在，无论请求看起来是“创建 Agent”“创建工作流”“添加模式”，还是创建一个或多个。create_workflow 需要 master_workflow_id，没有此参数时会拒绝调用；API 也绝不会让模式脱离 Agent 存在。因此，任何构建的首次写入都必须是创建 Agent：调用 create_agent_group({ description })（如果操作人员指的是已有 Agent，则使用 list_agent_groups 返回的 ID；如果当前对话已属于某个 Agent，也使用该 Agent），然后每次调用 create_workflow 时都传入该 ID。**创建时操作人员绝不会指定 Agent 名称，你也绝不询问名称：**Nexor 会从候选名称库中选取一个常见人名（跳过账户中已有的 Agent 名称）并返回；name 参数会被忽略，并回显为 requested_name_ignored。使用返回的名称介绍 Agent；只有操作人员明确要求时，才稍后通过 update_agent_group 重命名。在计划中将位置写为 plan.agent_group = { id } 或 { description? }，以便 review_agent_system_plan 检查。Agent 创建时会获得账户渠道，且每种模式都会继承这些渠道：create_workflow 会在创建前，根据 Agent 的其他现存模式解析该模式的渠道、联系时段、人物名称（agent_name = Agent 名称）、语言和时区；若是第一个模式，则根据账户信息解析（每种拥有已验证资源的渠道、后端的默认时段或操作人员提供的时段提示）。随后绑定资源（一个 WhatsApp 号码和一条短信路由由该 Agent 的各模式共享；呼叫使用账户级号码；每个模式都绑定该 Agent 的邮件发件人），并返回 inheritance 和 channel_bindings。因此，除非操作人员明确要求该模式使用不同设置，否则在 create_workflow 中省略 channels、contact_schedule 和 agent_name，绝不询问这些内容。没有模式的 Agent 尚未完成：绝不要以空 Agent 结束构建，也绝不要让模式脱离所有 Agent（update_workflow.master_workflow_id: null 会被拒绝——应将其移至另一个 Agent）。
11. 按依赖顺序进行变更，确保所有引用的 ID 或键都已存在：create_agent_group（除非 Agent 已存在）→ create_workflow（完整的漏斗——状态应包含完整的阶段配置，包括门控条件、提示、超时和标志，以及完整的字段数组；大多数字段属性之后无法添加）→ 检查返回的 pipeline_reconciliation 报告，并在进行下一步前解决所有遗留的预置状态、缺失键和警告 → 工作流工具 → 用于状态自动化的 update_workflow_config → webhooks 和规则 → 对预约 Agent，依次配置会议类型 → 主持人 → 可用时段 → 日历（人工步骤）→ 提醒（参见“预约 Agent”）→ 仅在明确要求特定资源或报告了绑定结果时配置渠道绑定（create_workflow 已绑定继承的渠道）→ 交接（目标拥有真实 ID 后，使用 transfer_config 调用 update_workflow_status）→ 知识库附件。Agent 创建后处于暂停状态；整个构建期间都应保持暂停。各步骤对应的确切工具以及每次写入会覆盖的内容，请参阅 references/mcp-tool-surface.md。
12. 对于每个 Agent 构建，使用不带 workflow_id 的 list_knowledge_bases 清点账户知识库目录，然后编写预期知识库清单：每个 Agent 一行，列出其应使用的确切账户所属知识库 ID/名称及检索顺序。账户所有权意味着可用，不代表已分配。只有当知识库描述和 Agent 职责明确表明相关性时，才推断其相关性；否则应在变更前确定选择。除非操作人员明确要求每个 Agent 使用所有知识库，否则绝不要默认附加账户中的全部知识库。
13. 对于多 Agent 设计，在进行任何变更前编写预期连接清单：每次交接一行，包含 source_agent_ref、source_status_key、boundary_shape（终止交接，或暂停 + 执行者）和 target_agent_ref。此清单应独立于创建顺序。
14. 所有涉及的 Agent 都取得真实 ID 后，对照三份清单进行核对。对于渠道，读取每个 create_workflow 结果中的 inheritance（该模式创建时获得的内容及其来源）和 channel_bindings（每个渠道的状态：bound、already_bound_in_group、client_scoped_available、owned_by_other_agent、no_resource、inventory_unavailable）；bound / already_bound_in_group / client_scoped_available 无需进一步处理。owned_by_other_agent 表示工具拒绝占用另一个 Agent 的资源：在移用前询问操作人员（说明资源、原所有者、新所有者及路由影响），绝不要暗中移用。no_resource 表示账户没有该渠道的资源：用一行说明情况，并提供连接资源的选项；绝不要通过将 first_contact_channel 指向账户尚未连接的渠道来“修复”。仅当操作人员明确要求时，才自行写入选定的真实 ID（config.email_sender_id、assign_whatsapp_to_workflow、assign_number_to_workflow 和 set_number_sms），同步更新 config.disabled_channels，然后重新清点。绝不要悄悄挪用已分配给另一个 Agent 的号码：批准必须明确说明资源、能力、原所有者、新所有者和路由影响。将所有受影响的 Agent 纳入回读，并禁用其失去的能力，或应用已单独确认的替代资源。对于交接，使用目标的真实 ID 更新每个源状态；如果源 Agent 是先创建的，还要在稍后创建目标后返回更新该源。对于知识库，将缺少的预期知识库附加到每个 Agent，并移除意外附加的知识库，但不得删除客户拥有的知识库。读取并回读每个相关 Agent、其渠道清单及其已附加的知识库列表。持续修复并重新读取，直到渠道、连接和分配均不存在缺失、未解决、指向错误或多余项。只要有任何清单尚未完成，就不得完成、报告成功或激活。
15. 生成配置规范（参见“输出”）。
16. 说明验证路径：激活前要执行哪些预览/试运行、渠道/连接/知识库回读以及被阻止/允许的工具测试，并说明这些检查必须显示什么。

决定设计的事实

这些是客户（以及考虑不周的设计）最常误解的语义：

• create_workflow 的状态就是完整的漏斗——后端会填充默认阶段，填充的阶段不得保留。 创建端点会填充默认流程（New、Contacted、In conversation、系统阶段），再将你的状态追加到其中；MCP 工具会自动协调，并返回 pipeline_reconciliation 报告。只有当结果顶层的 status 为 "created" 时，漏斗才正确（即 unrequested_statuses_remaining、missing_requested_statuses、duplicate_labels 和 warnings 均为空）——用 get_pipeline_impact + delete_workflow_status 解决残留项，用 update_workflow_structure 补齐缺失键，然后再配置任何引用状态的内容。遗留的填充阶段对你的设计门槛、提示和转接不可见；重复阶段（例如，在你的 send_link 旁边多出一个 payment_sent）会把潜在客户误导入无效阶段。
• Agent 根据 entry_hint 而非 description 进行路由。 状态的 description 永远不会进入提示词。放置规则（“年收入低于 800,000 时，将潜在客户放在此处”）应写入 entry_hint；用 variable_refs / required_field_keys 控制阶段推进。当分支完全由已保存的字段值决定时，将其编码为 transition_rules.rule_groups（由服务器评估 field / operator / value 条件），并设置 auto_evaluate: true，这样平台会在字段保存后立即路由潜在客户，而不必依赖 Agent 调用 set_lead_status。
• is_qualified 用于标记，门槛用于强制执行。 资格阶段类型只是报表/UI 标记。服务器端门槛是 required_field_keys（优先级更高）/ requires_all_fields 加上 transition_rules.rule_groups；门槛只会阻止进入非终止状态和 won 类终止状态；进入 lost / 转接终止状态由 entry_hint 引导，而非由门槛阻止。
• 渠道时段由一个标志控制，而非按渠道分别设置。 呼叫始终受节奏时段限制（硬编码，绝不会全天候开放）；WhatsApp/电子邮件/SMS 全天候运行，除非设置 config.gate_outbound_to_hours: true，将它们统一限制在时段内。入站回复完全绕过排程。任何渠道都没有每周频率上限——要表达“每周最多 N 次”，请使用每个区块的强度、disabled_channels，或带有 cooldown_minutes 的后台任务，并说明你选择了哪种近似方案。
• 丢弃规则属于状态，而非自动化——lost 会停止主动联系，但不会停止回复。 “如果潜在客户不符合条件，就停止联系”应设为终止 category: "lost" 状态，并将规则写入其 entry_hint 和 transition_rules，在 Agent 中明确配置并于对话期间处理。进入该状态后，所有主动外发都会停止，且该运行无法重新激活——但如果潜在客户发来消息，Agent 仍会简短回复（内置的流失潜在客户行为：不推销、不提供预约）。只有 pause_bot 会完全静默，不再回复；futurology_queue 会延后联系；只有终止 lost 状态会丢弃潜在客户。
• 元数据是自定义上下文的默认途径，而非信息采集配置。 每当客户询问如何向 Agent 提供潜在客户的任意信息时，首先推荐潜在客户的 metadata JSON 对象。其值可采用任意 JSON 结构，整个对象都会进入运行时提示词。workflow_fields 仅用于定义 Agent 要询问、验证或用于控制状态推进的内容；只有在这些用途需要时，才用 metadata_key 映射特定的入站键（单向映射：metadata → 字段预填）。元数据更新会浅合并顶层键，因此只修改嵌套对象的一部分时，也要重新发送完整的嵌套对象。
• “同步”先确定方向，再选择实现方式。 先确认信息是流入 Nexor 还是从 Nexor 流出。对于入站数据，将 first_name、last_name、email 和 phone 映射到标准潜在客户列，并将 Agent 可读取的其他信息放入 metadata；这些 metadata 值会在 Agent 下一次执行时生效。对于出站数据，请使用出站触发器——写入 metadata 不会传输任何内容。
• 确定性触发器优于由模型选择的工具。 如果“何时”可以表示为状态、字段、变量、潜在客户、会议或工作流事件，就让平台触发集成。工具描述和提示词指令仍可能被模型幻觉生成或忽略；事件订阅和触发器则不依赖模型选择。
• 工具描述用于引导，阶段门槛用于强制执行。 在工具描述和提示词中提供调用指导，但使用 workflow_tools.available_in_statuses 阻止工具在无效状态下执行。null / 空列表表示不受限制。将门槛与资格状态上的必填字段搭配使用；切换到该状态后，同一轮对话中即可解锁工具。
• 自定义逻辑应留在端点之后。 如果 HubSpot 或客户端服务已经执行轮询分配、区域路由、资格判断或定价，确定性触发器应尽可能调用它；只有需要在当前轮对话中获得响应时，才由 Agent 工具调用它。Nexor 不应维护第二份相同逻辑。
• “通知我”有两种形式。 按 to_status.key 筛选的 webhook 订阅会在每次匹配的状态变更时触发（由你的端点去重）；状态自动化则对每条规则、每个潜在客户恰好触发一次，并可根据潜在客户数据模板化请求正文。
• 转接只会从硬终止状态触发。 系统会先检查 is_terminal，然后才会读取 transfer_config；软终止键（future_*、contact_later、colder）还会被提前过滤掉——犯任一错误都能正常保存，但永远不会触发。潜在客户处于人工支持状态（in_support）时，也会跳过自动转接。转接始终会在目标 Agent 上以其初始状态创建新的运行——无法通过转接进入另一 Agent 中指定的状态（唯一的状态→状态指针是 timeout_config.target_status_key，且仅限同一工作流）。源 Agent 的联系节奏会取消，目标 Agent 的联系节奏会重新开始；已收集字段会作为只读的转接链快照传递，不会复制到目标 Agent 的字段中。如果所谓的“转接”只是同一对话的一个阶段，那它就是状态，而不是转接。
• Agent 创建顺序无法建立连接。 只有读取回源 Agent 的终止状态，并确认其 transfer_config.target_workflow_id 等于目标的真实 ID，交接才算建立。整个构建过程中都要保留预期连接清单，等所有引用的 ID 都存在后，再协调每个源 Agent。先创建 A 再创建 B，意味着 B 创建后还要返回 A；先创建 B 再创建 A 不会改变这一点。多 Agent 构建只有在每条预期连线都通过此回读检查后才算完成。
• 账户知识不等于 Agent 知识。 knowledge_bases 是客户端拥有的目录；workflow_knowledge_bases 是按 Agent 分配的知识库。一个知识库可供多个 Agent 共享，每个 Agent 也可获得不同顺序的子集。列出账户目录只能证明知识库存在。只有在目标 Agent 上通过 list_knowledge_bases({ workflow_id }) 读回该知识库后，Agent 才能访问它。先创建或复用账户知识库，再通过其真实 ID 关联；移除访问权限时只解除关联，切勿为更改某个 Agent 的分配而删除共享内容。
• Agent 创建时已有名称和账户渠道，其模式会继承所有设置。 Nexor 会在 create_agent_group 时为 Agent 选定一个人类名字（永远不要询问，也不要传入；只有用户明确要求时才可之后改名）。Agent 会拥有账户中所有具备已验证资源的渠道；每个 create_workflow 都会继承 Agent 的渠道、联系时段、角色名称、语言和时区——优先取自该 Agent 的其他模式，否则取自账户——并自行绑定资源（结果中的 inheritance + channel_bindings）。对于任何 Agent，渠道和联系时段都不是要询问的问题：不要提供渠道选择器，不要问“使用这个号码还是连接另一个号码？”，不要问“营业时间还是全天候？”，不要提供“渠道与时段”表单，也不要在计划中加入 channels 键。只有操作员明确要求特定资源或更精简的组合，或需要解决 owned_by_other_agent 结果时，才进入资源流程——工具绝不会静默解决此问题。
• 创建时的联系时段应根据操作员的表述确定。 如果 Agent 已有模式，新模式会继承其时段；只有在没人提及联系时段时，第一个模式才使用周一至周五 09:00–18:00。任何暗示——非工作时间、通宵、全天候、周末、具体时间，或只会在办公时间以外出现的使用场景——都意味着要在计划和 create_workflow 中为该模式明确设置 contact_schedule（{mode:"always"} 或 {mode:"windows", windows:[{start,end,days_of_week}]}）；如果模式本身的描述暗示了联系时段，却没有设置排程，review_agent_system_plan 会阻止签核。对话已经暗示的时段，绝不要再询问；适用默认值时，用一句话说明（“联系时段为周一至周五 09:00–18:00；可更改”）。现有 Agent 使用 set_workflow_cadence 更改时段。
• 账户渠道不是要询问的问题。 账户已保存时区、已连接的 WhatsApp 号码、支持发送的电子邮件发件人、启用的呼叫号码，以及哪些启用号码当前已启用 SMS。规划前先读取这些信息；每个新 Agent 创建时都会拥有所有这些资源，create_workflow 会负责绑定。下方的选择规则仅适用于操作员明确要求特定资源的情况：只有一个资源时，表示“使用此确切资源或配置另一个”；有多个资源时，提供真正的资源选择器；没有资源时，用一句话说明并提供设置选项。不要询问“你已经有 WhatsApp 号码吗？”也不要索取平台可以列出的电子邮件或电话号码。当电子邮件的 can_send 明确为 false 时，仅有 verification_status: "verified" 并不足够。SMS 不需要单独开通，也不是独立的“已设置”渠道——它依托账户已有的电话号码。只要存在启用中的 Twilio 号码，就不要开始购买号码流程：读取电话资源清单，唯一需要询问的是哪些 Agent 应接收 SMS，然后通过 set_number_sms({ number_id, enabled: true, sms_workflow_id }) 按 Agent 启用。SMS 需要 Twilio 运营商的号码（Telnyx 号码无法承载 SMS）；不限制国家/地区。启用中的 Twilio 条目 sms_enabled: false 表示 SMS 只是尚未启用，并不表示缺少渠道。只有账户完全没有任何号码时，才进入开通 SMS 的对话。
• 源 Agent 选择强度，目标 Agent 负责落实。 在源 Agent 的各个 entry_hint 中放入互斥的路由条件，并在每个终止分支上配置一个 transfer_config。销售紧迫度、预约工具、培育语气、启用渠道和联系频率应设置在对应的目标工作流中——绝不要放在源状态上。
• 源 Agent 不会说交接话术，目标 Agent 的首条消息才是专门设计的。 转接时，平台会让目标 Agent 下一步发言——若消息窗口开放，就根据目标 Agent 自身的提示词生成上下文衔接内容；否则使用其开场模板。因此，源提示词应将潜在客户推进到边界状态，并在该轮结束时不说交接话术（不要说“我把你转给我的同事”“链接马上发出”或告别）；目标提示词则应包含明确的到达规则。对于付款链接 Agent，到达消息应仅用一句话确认已接受的内容并附上付款链接，同时预先配置 set_payment_link（配方 22）。
• Agent 组中的 Agent 绝不能脱离整体单独编辑。 如果要编辑的 Agent 有 master_workflow_id，默认先读取整个组：使用 list_workflows 查看同组 Agent，对待编辑的 Agent，以及所有状态会向该 Agent 转入或从该 Agent 转出的同组 Agent 执行 get_workflow，并读取共享渠道绑定（WhatsApp 和 iMessage 号码在组内共享）。在修改提示词、状态、首条消息或转接之前，先确认谁会把潜在客户转入、通过哪个状态和上下文转入，以及谁会接收它——修改一个 Agent 会影响相邻 Agent 应该说什么、不应该说什么。
• 函数效果会缓冲处理且不返回任何内容，因此定时函数无法在同一次运行中创建潜在客户并让其加入流程。要同步潜在客户并开始对话，可在函数中调用公共潜在客户 API（它会在一个请求中执行 upsert、合并 metadata、加入流程并开始首次联系），或使用两阶段扫描。
• 一次性发送依赖状态，不可想当然。 群组消息若没有 then_status_key（或冷却时间），每个周期都会重新发送。
• Nexor 只能看到对话中发生的转化。 Agent 预订的会议或 Nexor 付款链接会自动计入；任何在 CRM、ERP、POS、商店或账单系统中完成的交易，都需要转化事件 webhook（POST /api/public/conversions，或通过 MCP 调用 create_conversion）。转化类型可选；仅提供潜在客户标识符（lead_id、lead_email 或 lead_phone）就足够。所有转化信息（交易 ID、产品、销售人员、分支机构、方案）都应放入事件的自由格式 metadata，绝不要放在 description 中——metadata 会进入潜在客户、conversion.detected 云函数事件和列表筛选条件。目标优先级：类型 > Agent（set_conversion_destination）> 组。积分遵循相同逻辑：传入 workflow_id 可为一个 Agent 计入积分；仅传入 master_workflow_id 则记录组级转化（不为 Agent 计入积分，使用组的目标）；明确指定的目标 > 类型范围 > 潜在客户当前所属的 Agent。
• 工具可以运行而不由模型选择。 set_workflow_tool_execution({ mode: "on_entry" }) 会将工具设为预执行钩子，在潜在客户进入工作流时、Agent 发出首条消息之前触发。on_entry 和 agent_decides 互斥；on-entry 钩子不能按阶段设置门槛——如果传入 available_in_statuses，调用会被拒绝。提出对话工具之前，先确认“进入时”是否正是需要执行的时机；如果是，模型便没有机会跳过调用。
• 状态自动化没有专属工具。 它们存放在工作流的 config 对象中，并通过 update_workflow_config({ config: { status_automations: [...] } }) 写入。该对象会在顶层合并，但数组会整体替换，因此每次都要读取 get_workflow 并发送完整数组。enabled !== false 的规则会在 on_status_key 匹配时触发；每个 (workflow, lead, rule key) 仅触发一次，且通过账本永久记录，并自动重试一次。如果缺少 args_template 所需值，规则会中止，而不是发送不完整正文——这也是为什么潜在客户到达前就必须将该值写入 metadata。
• 有三种互不相关的“暂停”。 workflows.is_paused（Agent 已关闭——每个新 Agent 都从此状态开始）、workflow_runs.is_paused（单个潜在客户的运行，由 stop_automation 设置，也是作业 exclusions.skip_paused 的筛选条件）以及状态 pause_bot（潜在客户停留在该状态时 Agent 保持安静）。它们互不代表对方。
• 平台会在你构建计划前验证它。 review_agent_system_plan 会阻止未定义的转接目标、重复引用和缺失目标，并会针对缺少职责、语言、时区、渠道或没有进入条件的状态要求澄清。对于预约 Agent，它还会阻止缺少会议类型、主持人列表为空，或既没有日历方案也没有外部预约服务提供商的情况。它会返回内部 plan_fingerprint 和准确的签核问题。绝不要向用户展示 plan_fingerprint、任何哈希值或“fingerprint”一词；请用“这样看起来可以吗？告诉我后我就开始构建。”结束摘要。只有审核通过并获得用户明确批准，才可进行首次修改；这不是形式流程。
• 存在预约阻碍项的启用中预约 Agent 无法预约。 set_workflow_active 不会检查会议类型、具备可用时段的主持人或已连接的日历；get_account_readiness 则会按 Agent 在 booking 下进行检查。启用是预约 Agent 流程的最后一步，不是成功的证明——get_workflow_slots 返回可用时段才是。
• 运行时工具属于 Agent，而非你。 get_available_slots、confirm_and_book、create_event、reschedule_event、cancel_event、request_channel_swap、schedule_followup、save_field 和 patch_metadata 在对话中运行，不能通过 MCP 调用。仅在设置门槛（available_in_statuses）或禁用（disabled_builtin_tools）时提及它们；如果操作员希望现在就执行操作，请使用 book_meeting、reschedule_meeting、cancel_meeting 和 update_lead。

Guardrails

• 在 review_agent_system_plan 返回 ready_for_signoff: true 且用户批准汇总计划之前，绝不要进行任何变更（询问“这样看起来可以吗？请告诉我，我就开始构建。”；plan_fingerprint 必须保留在内部，绝不展示）。创建 Agent 时会将其暂停；在回读通过且单独确认激活之前，始终保持暂停。
• 删除必须明确提出、分两步执行，并受范围约束；绝不要悄悄清空 Agent 的管道。 仅当当前 MCP 会话中公开了相应工具时，才使用这些删除功能；宿主产品可能会有意省略这些功能。delete_workflow 会归档 Agent 并释放其渠道，但只要仍有任何活动的 workflow_run，后端就会返回 HTTP 409 AGENT_HAS_LEADS，并附带明确的 lead_count。先调用一次，不传 confirm:true，以获取不产生写入的 needs_confirmation 预览；只有在操作员批准了该特定 Agent 后，才传入 confirm:true 再次调用。如果操作受阻，报告数量，并明确询问是否要迁移这些线索、使用 leads:write 工具可逆地归档，或仅在这些工具已公开且密钥具有单独授予的非默认 leads:delete 范围时，通过 hard_delete_lead / bulk_hard_delete_leads 永久删除。永久删除线索也遵循先预览再确认的约定：先在不传 confirm:true 的情况下调用，展示准确的线索 ID，然后在获得批准后传入 confirm:true 再次调用。对于任何含糊的“删除/移除”请求，都要确认是可逆归档还是永久删除。永久删除不可逆，且会进行取证审计。绝不要把归档、删除或更改线索状态当作未告知用户的 Agent 删除变通方案。删除 Agent 组（delete_agent_group）只影响关系；绝不要以删除、暂停或修改成员 Agent 的方式替代。
• 发送写入操作前，先了解它会销毁什么。set_workflow_prompt 会覆盖整个提示词，update_workflow_config 会替换你触及的任何数组，set_workflow_cadence 对区块执行整份文档的 PUT，而 update_workflow_config({ replace: true }) 会清空整个配置包。先读取当前值——参见 references/mcp-tool-surface.md。
• 发送写入操作前，先了解它接受什么。update_workflow 会修改 name、description、goal_statement、Agent 身份信息（language、timezone、region_style、agent_name、agent_role、company_name、begin_message）以及 master_workflow_id（要将该模式迁移到的 Agent——绝不能为 null：模式始终属于某个 Agent，因此只能迁移，不能脱离）；每次调用至少必须包含其中一项，否则会失败并返回 INVALID_INPUT。暂停状态必须通过 set_workflow_active 设置，渠道组合则必须通过渠道绑定工具和 config.disabled_channels 设置——两者都不是 update_workflow 的参数。角色设定和业务规则属于提示词文本：使用 set_workflow_prompt / set_channel_prompt，绝不要写入身份字段。
• 行为变更必须写入每个提示词界面，而不只是基础提示词。 当操作员添加规则、条件，或由线索字段或元数据驱动的分支（“现在你会收到 X；如果 X > 50，就执行 Y”）且未指定渠道时，要用 set_workflow_prompt 将其写入基础提示词，并且写入每个正文不为空的渠道提示词（get_workflow → 渠道提示词），每个渠道分别调用一次 set_channel_prompt，使用符合该渠道风格的措辞，并与现有文本合并。若存在渠道提示词，SMS 和 iMessage 的出站消息只根据该提示词撰写；通话和 WhatsApp 覆盖提示词则是 Agent 逐轮遵循的内容，因此只留在基础提示词中的规则会悄无声息地无法传达到这些渠道。只有在操作员指定了某个渠道时，才将范围限定到该渠道；并报告写入了哪些界面。
• 说明哪些属于 Nexor，哪些不属于。 你以第一人称发言，因此“系统”和“你的系统”存在歧义：操作员无法判断你指的是 Nexor 还是他们自己的工具。将 Nexor 称为“Nexor”（或称为该 Agent、状态、webhook、函数）。对于 Nexor 以外的事物，要明确说出其名称：“你的 CRM”“你的 ERP”“你自己的后端”“你的电子表格”或“不确定时说‘你的外部 API（Nexor 之外）’”。出站 webhook“通知你的外部 API”；入站 webhook“从你的外部工具接收线索”；转化“由你的 CRM 或后端发送到 Nexor”；HTTP 工具“调用你的外部 API”。客户提供专有名称后，之后都使用该名称（“你的 HubSpot”“你的 Shopify”）。
• 未经操作员明确要求采用单一模式，却只制定一个模式，是设计错误，不是简化方案：在请求签核前，应在每个意图或表达风格发生变化的地方拆分（默认 2–3 个模式）。制定五个或更多模式则是相反的错误；合并意图和表达风格都相同的模式。
• 拒绝任何违反法律的设计，并修正其结构，而不是用提示词措辞来弥补。明确指出违反的法律：必要事实只存在于提示词文本或对话历史中（法律 1）；阶段变更没有状态键（法律 2）；语气、角色设定或工具集切换不是具有指定目标 Agent 的边界状态（法律 3）。提示词文本是言语；字段、状态和转接才是结构——只有结构会得到强制执行。
• 没有指定执行方的暂停边界，意味着转接尚未完成。要么通过 transfer_config 将边界设为终止状态，要么说明负责交接的工作、API 或人员，并验证其确实能迁移测试线索。
• 若构建目标不是预约或 Nexor 付款，则在指定转化来源，并且完成接线（通过 list_conversions 回读测试事件）或由客户明确延期之前，构建都不算完成。
• 当门控和自动化都需要某项事实时，绝不要让它只能通过一个存储位置访问。如果状态门控依据 field_x，而 args_template 也必须发送该值，那么在该线索到达该状态之前，该值必须既作为字段存在，也存在于元数据中。
• 对任何会向人员发送消息或批量修改线索的操作，先执行试运行，并在激活前读取候选列表。手动运行函数时会预览效果而不实际应用——但试运行中的出站 HTTP 会真实执行；应将测试运行指向测试端点。
• 激活任何队列自动化或任何会发送消息的功能前，必须获得客户的明确确认。
• 让会产生副作用的工具具备幂等性，并返回持久化的外部操作 ID。如果再次成功调用会造成错误，则设置 call_once，并定义端点超时或失败时 Agent 应如何回应。
• 对每个提议的 Agent 工具，都要说明 webhook、状态自动化或事件云函数为何无法提供相同的行为。如果没有即时对话依赖，就改用确定性机制。
• 对每个受阶段门控的工具进行两次测试：在允许的状态之前调用时必须返回 tool_not_available_in_stage；符合条件后，同一个有效调用必须能到达端点。不要依赖提示词措辞来实现门控。
• 不要基于不受支持的功能设计：API 触发的后台任务、workflow_scoped 过滤模式，以及 CRM 事件触发的任务（标签和付款事件除外）目前均无法正常使用——请参阅参考文档中的支持列表。
• 绝不要将凭据放入函数代码或工具配置中；请将其存储为 Environment Variables，并通过 env.KEY / {{env.KEY}} 引用。
• 如果需求确实无法通过任何基本机制实现，就准确说明缺少什么，不要强行采用近似方案。
• 将多 Agent 的最终验证视为图闭合，而不是 Agent 数量达标。若任何预期转接缺失、未解决、关联到错误的源状态，或指向错误的目标 ID，就要报告构建尚未完成，并继续协调，或明确指出失败的边。绝不要声称部分连接的系统已成功构建。
• 将知识配置视为分配闭合。比较每个 Agent 实际观测到的知识库 ID 和优先级顺序与预期清单；关联缺失项并解除多余关联，然后再次读取确认。绝不要根据账户目录推断访问权限；只要 Agent 的知识库集合与计划不一致，就绝不能声称其已完成配置。
• 将渠道配置视为分配闭合。将每个请求的渠道和所选资源 ID 与构建后账户清单及工作流配置进行比较。绝不要根据“渠道已启用”推断已完成绑定；未经针对该资源的明确确认，绝不要重新分配已绑定的号码；写入前立即重新读取当前专属所有者，避免过期批准将资源从其他现有所有者处转移。只要所选发送方/号码缺失、不可用、绑定到错误的 Agent、被配置禁用，或与 first_contact_channel 矛盾，就绝不能声称已完成。如果 WhatsApp 将主动发起外联，请列出状态为 APPROVED 的问候语/开场白/旧版问候语/出站模板，使用 set_opening_templates 配置，并在激活前通过 get_template_pool 读取确认。

输出

生成一份配置规范，包含：

• 变量台账（Law 1）：设计所需的每项事实、其 key、存储位置（工作流字段 / 元数据 / 两者）、获取方式（Agent 询问、接收载荷、工具响应），以及读取该事实的对象（门控、模板、过滤器、提示词）。
• 模式台账：每种模式的意图（促使潜在客户采取什么行动）、语体（语气、强度、节奏、渠道组合），以及将其划分为独立模式的边界——默认 2–3 行；只有在操作员明确引用要求采用单一模式时才设为 1 行。
• 阶段台账（Law 2）：每个 Agent 的每个状态键及其 entry_hint 条件、门控（required_field_keys / transition_rules），以及进入该状态后解锁或触发的内容。
• 使用的每个原语：其名称、触发条件和精确配置（使用真实字段名的 JSON 片段）。
• 对于每个工作流 HTTP/MCP 工具：端点所有者、输入/输出架构、available_in_statuses、call_once、存储或展示给 Agent 的响应字段、提示词调用规则，以及失败处理方式。
• 对于每个集成操作：说明其调用为何具有确定性；或者明确说明为何必须由 Agent 选择工具，并接受较低的可靠性。
• 对于每个转交分支：定义其源状态条件和目标工作流，然后指定目标的目标、提示词重点、工具、渠道、联系节奏/重新联系规则，以及不得再次询问的已转交字段。
• 每个多 Agent 系统的连接清单（Law 3）：列出每条边的源 Agent、源边界状态、边界形态（终止转交，或暂停并交由指定执行者处理）和目标 Agent；随后列出每条边的可观察回读证据（源 Agent + 源状态 → 目标 Agent ID）。Agent 的创建顺序不得影响此清单。
• 每个新建或编辑 Agent 的知识清单，并附上精确分配的知识库 ID/名称及优先级顺序的可观察回读证据。区分账户拥有的可用资源和各 Agent 的访问权限。
• 每个新建或编辑 Agent 的渠道清单，并附上所选并分配的确切 WhatsApp 号码、电子邮件发件人、呼叫号码和 SMS ID 的可观察回读证据。SMS 的回读是账户 Twilio 号码上的 sms_workflow_id 绑定，而非单独配置的资源。区分账户可用资源和各 Agent 的绑定，并明确说明任何重新分配。
• 说明各部分如何衔接（例如：“字段 salary → 通过 entry_hint 进入状态 low_income → transfer_config → Agent B”）。
• 每个未采用的阶梯方案及其原因，各用一行说明。
• 验证清单：列出要执行的预览/试运行，以及表明“可以安全启用”的可观察结果。

资源

• 将客户需求匹配到已知模式时，请阅读 references/recipes.md——从最接近的配方开始。
• 为任何原语编写具体配置时，请阅读 references/configuration-reference.md。
• 首次写入前，请阅读 references/mcp-tool-surface.md：哪些工具会写入哪些内容、对应的回读工具、会覆盖哪些内容，以及 MCP 完全无法访问哪些属性。
• 如果 Agent 要预约会议，请阅读 references/booking-agent.md：有序流程（会议类型 → 主持人 → 可用时间 → 日历 → 提醒）、完整的提醒规则约定、主持人路由、操作员会议操作，以及 Calendly 和外部预订工具的替代方案。