Data Add

data-add

把用户的自然语言变成一条可落库的 CRM 记录。整条链路是一个串行的解析过程：

准备新建表单 → 组装 object_data → 保存 → 返回结果

每一步都依赖上一步的真实返回值。这条 skill 的核心风险只有一个：在信息还没确定时就往下猜——猜错对象、猜错业务类型、给只读字段回填值、编造关联记录 ID。这些都会写出一条错误的脏数据，而且用户往往要事后才发现。所以下面每一步的约束，本质都是在回答同一个问题：“我现在掌握的信息，足够让我安全地走下一步吗？” 信息不足时，宁可停下来问用户，也不要编造。

工作流总览

一个贯穿全程的原则：用户中途改了任何会影响结果的信息（对象、业务类型、字段值、关联记录、明细），就从受影响的最早步骤重新走一遍，不要复用旧的表单元数据。

步骤 0：对象专属逻辑（命中即先读）

有些对象有超出通用规则的特殊构造逻辑。组装前先按下表判断是否需要读引用文件：

命中时先读对应文件并应用其约束，再构造 object_data。引用文件里的特殊构造逻辑优先于通用规则；但可写字段、必填状态、枚举提交值仍以本次新建表单返回为准。

步骤 1：准备新建表单

先做语义拆分。 用户一句话里常同时含两类信息：①对象类型（要建哪类记录，如“客户 / 商机 / 联系人”），②记录本身的名称或字段值（如“大麦网”“王小二”）。对象识别阶段只使用对象类型词；记录名称和字段值留到步骤 2 处理。

如果一句话里识别不出明确的对象类型词，不要把记录名硬当对象名传进去，先向用户确认要建哪一类对象。

1.1 识别对象

对象 apiName 未知时，调用对象识别工具：

{
  "apiName": "IdentifyObjectWithDescribe",
  "query": "<对象名称>",
  "include_simple_describe": false
}

处理规则：

• resolution_status = RESOLVED 且仅 1 个候选：采用该 object_api_name
• resolution_status = AMBIGUOUS：把 object_candidates 交给用户确认
• resolution_status = NO_MATCH 或无可用候选：请用户更换对象名称或确认对象是否存在

对象 apiName 已明确时，直接跳过对象识别。

1.2 确定业务类型

调用业务类型列表工具：

{
  "apiName": "getRecordTypeList",
  "object_api_name": "<object_api_name>"
}

处理规则：

• 只有 1 个业务类型：直接采用其 value
• 有多个业务类型：把候选列给用户选
• 没有可用业务类型：停止并告知无法继续创建

1.3 获取新建表单

调用新建表单工具：

{
  "apiName": "getCreateFormContext",
  "object_api_name": "<object_api_name>",
  "record_type_apiName": "<record_type>"
}

返回中的以下三部分是后续组装数据的唯一真相：

• form_fields
• field_metadata
• initial_object_data

同一对象 + 同一业务类型可复用上一份表单，不要重复请求。 如果本轮对话里刚刚已经为某个对象拉过同一 record_type 的表单，直接复用上一次返回的 form。

步骤 2：组装 object_data

以 initial_object_data 为初始值，写入步骤 1 已确定的 record_type，再合并从用户输入解析出的字段值。只认步骤 1 返回的这份表单，三条铁律：

1. 只读字段是雷区。 form_fields 中 is_readonly=true 的字段原样保留 initial_object_data 里的值，绝不写入用户值、默认补值、推断值或计算值。
2. 必填以 is_required 为准。 必填字段缺用户输入又没有默认值时不要编造，先向用户补问。
3. 选项字段只认提交值。 field_metadata 里带 options 的是选项类字段，必须写其中的合法 value 而非展示名；映射不唯一时先确认。

2.1 关联对象字段（必须解析到唯一 ID）

关联记录的解析只在这一步做，前提是表单里确实存在这个关联字段。先在 form_fields / field_metadata 里确认该字段存在，并拿到它的真实 field_name 和关联对象 apiName。

当字段类型是 object_reference，或元数据表明该字段要关联已有记录时，必须先解析成唯一可提交的记录 ID 再写入。

解析路径：

• 用户直接给了符合字段要求的明确 ID：可直接用
• 用户给的是名称 / 编号 / 手机号 / 公司名 / 联系人名等文本：从该字段 field_metadata 中读取关联对象 apiName，再调用按名称查询记录 ID 工具

{
  "apiName": "QueryRecordIdByName",
  "query": "<关键词>",
  "apiNames": ["<关联对象apiName>"]
}

需要查看候选详情再让用户判断时，再调用按名称查询候选记录工具：

{
  "apiName": "QueryRecordByName",
  "name": "<关键词>",
  "object_api_names": ["<关联对象apiName>"]
}

处理规则：

• 查到 1 条：可用
• 查到多条：交给用户选择
• 查不到 / 无法判断：停下来，不要编造 ID 或默认选第一条

2.2 各字段类型的写法

步骤 3：保存数据

object_data 组装完成后，直接调用创建记录工具。格式校验、必填校验等都交给保存接口负责。

仅主对象：

{
  "apiName": "CreateRecordsByData",
  "object_api_name": "<apiName>",
  "object_data": {
    "...": "..."
  }
}

带从对象明细：

{
  "apiName": "CreateRecordsByData",
  "object_api_name": "<apiName>",
  "object_data": {
    "...": "..."
  },
  "details": {
    "<DetailObjectApiName>": [
      {
        "...": "..."
      }
    ]
  }
}

步骤 4：返回结果

调用创建工具后，先判断接口返回，只有记录确实创建成功时才作为成功返回。

• 需要二次确认：把系统要求确认的内容如实转达给用户，等用户确认后再重新提交
• 用户明确拒绝本次创建：立即终止整个操作
• 权限 / 禁止执行 / 当前对象不支持：立即终止，不重试
• 保存失败 / 报错：把失败原因如实告诉用户；仅当错误明确指出某个可修正字段问题时，修正后至多重试一次