AI 数据助手：让 Linker 数据听你说话 ​

Linker 的 AI 数据助手 是基于 MCP（Model Context Protocol）服务提供的能力包，让支持 MCP 的 AI 客户端（Claude Desktop、Cursor、Cline、各类智能体框架）能用自然语言直接查询、新增、修改、批量维护 Linker 中的业务数据。

它的设计目标是：把"业务人员描述数据操作，IT 翻译成代码或脚本"这两步合并为一步，让业务人员对 AI 说一句话，AI 自己完成"识别实体 → 查字段 → 校验 → 执行 → 回查"。

一、适合哪些企业 ​

  • 销售团队 3 人以上：客户、跟进、商机、回款数据频繁更新，需要高效批量维护。
  • 客户成功 / 售后团队：定期批量调整客户阶段、健康度、续约日期等。
  • 市场 / 运营团队：批量打标签、改来源、跨实体搬运线索。
  • 老板 / 销售主管：临时性的数据整理需求，不必每次都提给技术。
  • 多业务线协同：跨实体查询、批量导入后的回写、明细记录同步。

二、核心能力 ​

2.1 元数据查询（AI "看懂"你的系统） ​

工具作用
list_entities列出所有可操作实体
get_entity_metadata获取某实体的完整元数据
list_fields列出实体的字段（内部名、显示名、类型、是否可创建/修改）
list_field_types列出 Linker 支持的字段类型
list_cascade_fields列出可用于查询和引用的级联字段
get_field_options获取下拉 / 多选字段的全部选项值
resolve_entity_name按显示名反查实体内部名
resolve_field_name按显示名反查字段内部名

为什么先做元数据查询

所有写操作都依赖"实体内部名 + 字段内部名 + 字典值"。让 AI 先调这些工具确认结构，是避免误操作的前提。

2.2 数据读写 ​

工具作用是否可逆
query_records按条件分页查询业务记录—
get_record按记录 ID 查询单条记录—
save_record新增或修改一条记录否
batch_save_records批量新增 / 修改否
  • query_records 支持原生 SQL 条件片段（使用字段内部名），例如 status = 2 AND createdTime > '2025-01-01'。
  • save_record 不含 ID 为新增，含 ID 为更新（只更新传入字段）。ID 与字典值均以字符串传入。
  • 需要同时保存明细时，可在 values 中附带 details 数组。

2.3 明细记录 ​

工具作用
get_detail_records按主记录 ID 查询关联的明细实体记录

三、典型场景 ​

  1. 月末批量调状态：把所有沉睡超过 90 天的客户状态改为"待激活"，负责人统一改给指定销售。
  2. 销售离职交接：把离职销售名下的客户批量改负责人、清理活跃跟进、归档历史数据。
  3. 跨实体整理：把一批"演示客户"从客户实体搬到回收站；把线索实体里满足条件的记录升级到商机实体。
  4. 批量回写：根据外部 Excel 或 BI 结果，在 Linker 中批量补字段、改阶段。
  5. 明细同步：合同主表保存时同步写入多条交付明细，AI 自动组装 details 数组。

四、接入方式 ​

Linker 的 MCP 服务基于 Streamable HTTP，端点为 /open/mcp，鉴权沿用开放 API 的 X-Api-Key 请求头。

json
{
  "mcpServers": {
    "linker": {
      "type": "http",
      "url": "http://localhost:18000/open/mcp",
      "headers": {
        "X-Api-Key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

最小权限原则

为 AI 集成单独创建一个系统用户，按实际用途分配角色，再绑定到 API Key。不要使用管理员账号，除非确实需要结构管理能力。

详细配置步骤、客户端差异说明见 MCP 接口使用手册。

五、与开放 API、Excel 操作的关系 ​

通道适合场景谁来操作
MCP（AI 数据助手）自然语言查询、批量维护、临时整理业务人员、AI 智能体
开放 API定时同步、深度集成、自研系统对接开发人员
系统界面单条记录的增删改查业务人员
Excel 导入一次性大批量初次入库管理员

四者底层数据一致、权限一致，可以混用。

六、典型使用流程 ​

  1. 确认结构：让 AI 先调 list_entities / list_fields 弄清实体与字段内部名；只知道显示名时用 resolve_entity_name / resolve_field_name 反查。
  2. 读取验证：用 query_records / get_record 读取数据，确认要操作的对象。
  3. 执行写入：用 save_record / batch_save_records 新增或修改。
  4. 回查确认：写入后再查一次，确认结果符合预期。

七、在线体验 ​

如果你希望先看到效果再决定，可以：

  • 在 在线演示系统 用 admin / Admin123 登录，进入"系统设置 → 开放 API"创建一个绑定业务用户角色的 API Key。
  • 在 Claude Desktop / Cursor / Cline 中按上面的 JSON 配置连接，让 AI 试着帮你查一次客户列表、改一条客户状态。
  • 效果满意后，再为团队批量配置 AI 数据助手。

Linker